> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentNotFoundError(agentId: string)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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     |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentExecutionError(agentId: string, cause?: Error)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentLoopExceededError(agentId: string, maxIterations: number, actualIterations?: number)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentTimeoutError(agentId: string, timeoutMs: number)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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          |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentVisibilityError(requestingAgentId: string, targetAgentId: string)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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        |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentLlmError(agentId: string, cause?: Error)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentConfigurationError(message: string, options?: {
  agentId?: string;
  errors?: string[];
})
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentNotConfiguredError(agentName: string)
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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      |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new AgentToolNotFoundError(agentName: string, toolName: string, availableTools: string[])
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { AgentToolNotFoundError } from '@frontmcp/sdk';

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