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

# Remote Errors

> Errors for remote MCP server connections, operations, and configuration.

## Overview

Remote errors are thrown when interacting with remote MCP servers via the `@App()` decorator's remote app configuration. They cover connection failures, timeouts, not-found resources, auth issues, execution failures, transport problems, capability mismatches, configuration errors, and retry validation.

## Connection Errors

### RemoteConnectionError

Thrown when the initial connection to a remote MCP server fails.

| Property        | Type                 | Value                     |
| --------------- | -------------------- | ------------------------- |
| `code`          | `string`             | `REMOTE_CONNECTION_ERROR` |
| `statusCode`    | `number`             | `500`                     |
| `isPublic`      | `boolean`            | `false`                   |
| `appId`         | `string`             | Remote app identifier     |
| `url`           | `string`             | Target URL                |
| `originalError` | `Error \| undefined` | The underlying cause      |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteConnectionError(appId: string, url: string, originalError?: Error)
```

***

### RemoteDisconnectError

Thrown when a remote MCP server disconnects unexpectedly.

| Property     | Type                  | Value                     |
| ------------ | --------------------- | ------------------------- |
| `code`       | `string`              | `REMOTE_DISCONNECT_ERROR` |
| `statusCode` | `number`              | `500`                     |
| `isPublic`   | `boolean`             | `false`                   |
| `appId`      | `string`              | Remote app identifier     |
| `reason`     | `string \| undefined` | Disconnect reason         |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteDisconnectError(appId: string, reason?: string)
```

## Timeout Errors

### RemoteTimeoutError

Thrown when a remote MCP operation exceeds the configured timeout.

| Property       | Type      | Value                        |
| -------------- | --------- | ---------------------------- |
| `code`         | `string`  | `REMOTE_TIMEOUT_ERROR`       |
| `statusCode`   | `number`  | `504`                        |
| `isPublic`     | `boolean` | `true`                       |
| `appId`        | `string`  | Remote app identifier        |
| `operation`    | `string`  | The operation that timed out |
| `timeoutMs`    | `number`  | Configured timeout           |
| `mcpErrorCode` | `number`  | `-32603`                     |

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

**Example:**

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

throw new RemoteTimeoutError('slack', 'tools/call', 30000);
```

## Not Found Errors

### RemoteToolNotFoundError

Thrown when a tool is not found on the remote server.

| Property       | Type      | Value                   |
| -------------- | --------- | ----------------------- |
| `code`         | `string`  | `REMOTE_TOOL_NOT_FOUND` |
| `statusCode`   | `number`  | `404`                   |
| `isPublic`     | `boolean` | `true`                  |
| `appId`        | `string`  | Remote app identifier   |
| `toolName`     | `string`  | The missing tool        |
| `mcpErrorCode` | `number`  | `-32601`                |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteToolNotFoundError(appId: string, toolName: string)
```

***

### RemoteResourceNotFoundError

Thrown when a resource is not found on the remote server.

| Property       | Type      | Value                       |
| -------------- | --------- | --------------------------- |
| `code`         | `string`  | `REMOTE_RESOURCE_NOT_FOUND` |
| `statusCode`   | `number`  | `404`                       |
| `isPublic`     | `boolean` | `true`                      |
| `appId`        | `string`  | Remote app identifier       |
| `uri`          | `string`  | The missing resource URI    |
| `mcpErrorCode` | `number`  | `-32002`                    |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteResourceNotFoundError(appId: string, uri: string)
```

***

### RemotePromptNotFoundError

Thrown when a prompt is not found on the remote server.

| Property       | Type      | Value                     |
| -------------- | --------- | ------------------------- |
| `code`         | `string`  | `REMOTE_PROMPT_NOT_FOUND` |
| `statusCode`   | `number`  | `404`                     |
| `isPublic`     | `boolean` | `true`                    |
| `appId`        | `string`  | Remote app identifier     |
| `promptName`   | `string`  | The missing prompt        |
| `mcpErrorCode` | `number`  | `-32601`                  |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemotePromptNotFoundError(appId: string, promptName: string)
```

## Auth Errors

### RemoteAuthError

Thrown when authentication to a remote server fails (missing credentials).

| Property       | Type                  | Value                 |
| -------------- | --------------------- | --------------------- |
| `code`         | `string`              | `REMOTE_AUTH_ERROR`   |
| `statusCode`   | `number`              | `401`                 |
| `isPublic`     | `boolean`             | `true`                |
| `appId`        | `string`              | Remote app identifier |
| `details`      | `string \| undefined` | Additional details    |
| `mcpErrorCode` | `number`              | `-32001`              |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteAuthError(appId: string, details?: string)
```

***

### RemoteAuthorizationError

Thrown when authorization to a remote resource/tool fails (insufficient credentials).

| Property       | Type                  | Value                        |
| -------------- | --------------------- | ---------------------------- |
| `code`         | `string`              | `REMOTE_AUTHORIZATION_ERROR` |
| `statusCode`   | `number`              | `403`                        |
| `isPublic`     | `boolean`             | `true`                       |
| `appId`        | `string`              | Remote app identifier        |
| `resource`     | `string \| undefined` | The denied resource          |
| `mcpErrorCode` | `number`              | `-32003`                     |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteAuthorizationError(appId: string, resource?: string)
```

## Execution Errors

### RemoteToolExecutionError

Thrown when a remote tool execution fails.

| Property        | Type                 | Value                         |
| --------------- | -------------------- | ----------------------------- |
| `code`          | `string`             | `REMOTE_TOOL_EXECUTION_ERROR` |
| `statusCode`    | `number`             | `500`                         |
| `isPublic`      | `boolean`            | `true`                        |
| `appId`         | `string`             | Remote app identifier         |
| `toolName`      | `string`             | The failed tool               |
| `originalError` | `Error \| undefined` | The underlying cause          |
| `mcpErrorCode`  | `number`             | `-32603`                      |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteToolExecutionError(appId: string, toolName: string, originalError?: Error)
```

***

### RemoteResourceReadError

Thrown when reading a remote resource fails.

| Property        | Type                 | Value                        |
| --------------- | -------------------- | ---------------------------- |
| `code`          | `string`             | `REMOTE_RESOURCE_READ_ERROR` |
| `statusCode`    | `number`             | `500`                        |
| `isPublic`      | `boolean`            | `true`                       |
| `appId`         | `string`             | Remote app identifier        |
| `uri`           | `string`             | The resource URI             |
| `originalError` | `Error \| undefined` | The underlying cause         |
| `mcpErrorCode`  | `number`             | `-32603`                     |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteResourceReadError(appId: string, uri: string, originalError?: Error)
```

***

### RemotePromptGetError

Thrown when getting a remote prompt fails.

| Property        | Type                 | Value                     |
| --------------- | -------------------- | ------------------------- |
| `code`          | `string`             | `REMOTE_PROMPT_GET_ERROR` |
| `statusCode`    | `number`             | `500`                     |
| `isPublic`      | `boolean`            | `true`                    |
| `appId`         | `string`             | Remote app identifier     |
| `promptName`    | `string`             | The prompt name           |
| `originalError` | `Error \| undefined` | The underlying cause      |
| `mcpErrorCode`  | `number`             | `-32603`                  |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemotePromptGetError(appId: string, promptName: string, originalError?: Error)
```

## Transport Errors

### RemoteTransportError

Thrown when transport initialization fails for a remote app.

| Property        | Type                 | Value                    |
| --------------- | -------------------- | ------------------------ |
| `code`          | `string`             | `REMOTE_TRANSPORT_ERROR` |
| `statusCode`    | `number`             | `500`                    |
| `isPublic`      | `boolean`            | `false`                  |
| `appId`         | `string`             | Remote app identifier    |
| `transportType` | `string`             | The transport type       |
| `originalError` | `Error \| undefined` | The underlying cause     |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteTransportError(appId: string, transportType: string, originalError?: Error)
```

***

### RemoteUnsupportedTransportError

Thrown when an unsupported transport type is specified for a remote app.

| Property        | Type      | Value                          |
| --------------- | --------- | ------------------------------ |
| `code`          | `string`  | `REMOTE_UNSUPPORTED_TRANSPORT` |
| `statusCode`    | `number`  | `400`                          |
| `isPublic`      | `boolean` | `true`                         |
| `transportType` | `string`  | The unsupported type           |

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

## Capability Errors

### RemoteCapabilityDiscoveryError

Thrown when capability discovery fails for a remote server.

| Property        | Type                 | Value                               |
| --------------- | -------------------- | ----------------------------------- |
| `code`          | `string`             | `REMOTE_CAPABILITY_DISCOVERY_ERROR` |
| `statusCode`    | `number`             | `500`                               |
| `isPublic`      | `boolean`            | `false`                             |
| `appId`         | `string`             | Remote app identifier               |
| `originalError` | `Error \| undefined` | The underlying cause                |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteCapabilityDiscoveryError(appId: string, originalError?: Error)
```

***

### RemoteCapabilityNotSupportedError

Thrown when a remote server doesn't support a required capability.

| Property     | Type      | Value                             |
| ------------ | --------- | --------------------------------- |
| `code`       | `string`  | `REMOTE_CAPABILITY_NOT_SUPPORTED` |
| `statusCode` | `number`  | `400`                             |
| `isPublic`   | `boolean` | `true`                            |
| `appId`      | `string`  | Remote app identifier             |
| `capability` | `string`  | The missing capability            |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteCapabilityNotSupportedError(appId: string, capability: string)
```

## Configuration Errors

### RemoteConfigurationError

Thrown when a remote app's configuration is invalid.

| Property      | Type                  | Value                        |
| ------------- | --------------------- | ---------------------------- |
| `code`        | `string`              | `REMOTE_CONFIGURATION_ERROR` |
| `statusCode`  | `number`              | `400`                        |
| `isPublic`    | `boolean`             | `true`                       |
| `appId`       | `string`              | Remote app identifier        |
| `configField` | `string \| undefined` | The invalid field            |
| `details`     | `string \| undefined` | Additional details           |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new RemoteConfigurationError(appId: string, configField?: string, details?: string)
```

***

### RemoteNotConnectedError

Thrown when an operation is attempted on a remote app that is not connected.

| Property     | Type      | Value                  |
| ------------ | --------- | ---------------------- |
| `code`       | `string`  | `REMOTE_NOT_CONNECTED` |
| `statusCode` | `number`  | `503`                  |
| `isPublic`   | `boolean` | `true`                 |
| `appId`      | `string`  | Remote app identifier  |

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

## Retry Errors

### InvalidRetryOptionsError

Thrown when retry configuration is invalid (e.g., `maxAttempts < 1`).

| Property     | Type      | Value                   |
| ------------ | --------- | ----------------------- |
| `code`       | `string`  | `INVALID_RETRY_OPTIONS` |
| `statusCode` | `number`  | `500`                   |
| `isPublic`   | `boolean` | `false`                 |
| `option`     | `string`  | The invalid option name |
| `value`      | `unknown` | The invalid value       |

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
new InvalidRetryOptionsError(option: string, value: unknown, reason: string)
```

**Example:**

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

throw new InvalidRetryOptionsError('maxAttempts', 0, 'must be >= 1');
```