Agent Errors

Errors for agent lookup, execution, configuration, and LLM adapter failures.

Overview

Agent errors cover the full lifecycle of agent operations — from not-found and configuration issues to execution failures, loop limits, timeouts, and LLM adapter problems.

Error Reference

AgentNotFoundError

Thrown when a requested agent is not registered.

Property	Type	Value
code	string	AGENT_NOT_FOUND
statusCode	number	404
isPublic	boolean	true
agentId	string	The requested agent ID

new AgentNotFoundError(agentId: string)

Example:

import { AgentNotFoundError } from '@frontmcp/sdk';

throw new AgentNotFoundError('code-reviewer');

---

AgentExecutionError

Thrown when an agent’s execution fails unexpectedly. This is an internal error.

Property	Type	Value
code	string	AGENT_EXECUTION_FAILED
statusCode	number	500
isPublic	boolean	false
agentId	string	The agent that failed
originalError	Error | undefined	The underlying cause

new AgentExecutionError(agentId: string, cause?: Error)

Example:

import { AgentExecutionError } from '@frontmcp/sdk';

try {
  await agent.run(input);
} catch (error) {
  throw new AgentExecutionError('code-reviewer', error);
}

---

AgentLoopExceededError

Thrown when an agent exceeds its maximum iteration count.

Property	Type	Value
code	string	AGENT_LOOP_EXCEEDED
statusCode	number	400
isPublic	boolean	true
agentId	string	The agent that looped
maxIterations	number	Configured maximum
actualIterations	number	How many iterations ran

new AgentLoopExceededError(agentId: string, maxIterations: number, actualIterations?: number)

Example:

import { AgentLoopExceededError } from '@frontmcp/sdk';

throw new AgentLoopExceededError('planner', 10, 11);

---

AgentTimeoutError

Thrown when an agent exceeds its configured timeout.

Property	Type	Value
code	string	AGENT_TIMEOUT
statusCode	number	408
isPublic	boolean	true
agentId	string	The timed-out agent
timeoutMs	number	Configured timeout in milliseconds

new AgentTimeoutError(agentId: string, timeoutMs: number)

Example:

import { AgentTimeoutError } from '@frontmcp/sdk';

throw new AgentTimeoutError('planner', 30000);

---

AgentVisibilityError

Thrown when an agent attempts to invoke another agent it doesn’t have visibility to.

Property	Type	Value
code	string	AGENT_VISIBILITY_DENIED
statusCode	number	403
isPublic	boolean	true
requestingAgentId	string	The caller agent
targetAgentId	string	The target agent

new AgentVisibilityError(requestingAgentId: string, targetAgentId: string)

Example:

import { AgentVisibilityError } from '@frontmcp/sdk';

throw new AgentVisibilityError('assistant', 'admin-agent');

---

AgentLlmError

Thrown when the LLM adapter (e.g., OpenAI, Anthropic) fails during agent execution. This is an internal error.

Property	Type	Value
code	string	AGENT_LLM_ERROR
statusCode	number	500
isPublic	boolean	false
agentId	string	The agent using the adapter
originalError	Error | undefined	The underlying cause

new AgentLlmError(agentId: string, cause?: Error)

Example:

import { AgentLlmError } from '@frontmcp/sdk';

throw new AgentLlmError('planner', new Error('Rate limited by provider'));

---

AgentConfigurationError

Thrown when an agent has invalid configuration.

Property	Type	Value
code	string	AGENT_CONFIGURATION_ERROR
statusCode	number	500
isPublic	boolean	true
agentId	string | undefined	The misconfigured agent
configErrors	string[]	List of configuration errors

new AgentConfigurationError(message: string, options?: {
  agentId?: string;
  errors?: string[];
})

Example:

import { AgentConfigurationError } from '@frontmcp/sdk';

throw new AgentConfigurationError('Missing model configuration', {
  agentId: 'planner',
  errors: ['model is required', 'tools must be a non-empty array'],
});

---

AgentNotConfiguredError

Thrown when an agent doesn’t have an LLM adapter configured. This is an internal error.

Property	Type	Value
code	string	AGENT_NOT_CONFIGURED
statusCode	number	500
isPublic	boolean	false
agentName	string	The unconfigured agent

new AgentNotConfiguredError(agentName: string)

Example:

import { AgentNotConfiguredError } from '@frontmcp/sdk';

throw new AgentNotConfiguredError('planner');
// "Agent "planner" has no LLM adapter configured"

---

AgentToolNotFoundError

Thrown when a tool is not found in the agent’s allowed tool scope. This is an internal error.

Property	Type	Value
code	string	AGENT_TOOL_NOT_FOUND
statusCode	number	500
isPublic	boolean	false
agentName	string	The agent that requested the tool
toolName	string	The missing tool
availableTools	string[]	Tools available to the agent

new AgentToolNotFoundError(agentName: string, toolName: string, availableTools: string[])

Example:

import { AgentToolNotFoundError } from '@frontmcp/sdk';

throw new AgentToolNotFoundError('planner', 'delete_user', ['list_users', 'get_user']);