Agent Errors

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']);

Decorators

API

Errors

Overview

Error Reference

AgentNotFoundError

AgentExecutionError

AgentLoopExceededError

AgentTimeoutError

AgentVisibilityError

AgentLlmError

AgentConfigurationError

AgentNotConfiguredError

AgentToolNotFoundError

​Overview

​Error Reference

​AgentNotFoundError

​AgentExecutionError

​AgentLoopExceededError

​AgentTimeoutError

​AgentVisibilityError

​AgentLlmError

​AgentConfigurationError

​AgentNotConfiguredError

​AgentToolNotFoundError

Overview

Error Reference

AgentNotFoundError

AgentExecutionError

AgentLoopExceededError

AgentTimeoutError

AgentVisibilityError

AgentLlmError

AgentConfigurationError

AgentNotConfiguredError

AgentToolNotFoundError