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

# ESM Errors

> Error classes for ESM package loading, version resolution, manifest validation, caching, and registry authentication

Error classes thrown during [ESM package loading](/frontmcp/servers/esm-packages). Import them from `@frontmcp/sdk`:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import {
  EsmPackageLoadError,
  EsmVersionResolutionError,
  EsmManifestInvalidError,
  EsmCacheError,
  EsmRegistryAuthError,
  EsmInvalidSpecifierError,
} from '@frontmcp/sdk';
```

## Overview

| Error | Base Class | Error Code | HTTP | Description |
| - | - | - | - | - |
| `EsmPackageLoadError` | `InternalMcpError` | `ESM_PACKAGE_LOAD_ERROR` | 500 | Bundle fetch or module evaluation failed |
| `EsmVersionResolutionError` | `InternalMcpError` | `ESM_VERSION_RESOLUTION_ERROR` | 500 | npm registry version resolution failed |
| `EsmManifestInvalidError` | `PublicMcpError` | `-32602` (INVALID\_PARAMS) | 400 | Package manifest is invalid or missing required fields |
| `EsmCacheError` | `InternalMcpError` | `ESM_CACHE_ERROR` | 500 | Cache read/write operation failed |
| `EsmRegistryAuthError` | `PublicMcpError` | `-32001` (UNAUTHORIZED) | 401 | Private registry authentication failed |
| `EsmInvalidSpecifierError` | `PublicMcpError` | `-32602` (INVALID\_PARAMS) | 400 | Package specifier string is malformed |

***

## EsmPackageLoadError

Thrown when loading an ESM package fails — including network errors, CDN timeouts, and module evaluation failures.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmPackageLoadError extends InternalMcpError {
  readonly packageName: string;
  readonly version?: string;
  readonly originalError?: Error;
}
```

| Property | Type | Description |
| - | - | - |
| `packageName` | `string` | Full package name (e.g., `@acme/tools`) |
| `version` | `string?` | Resolved version that failed to load |
| `originalError` | `Error?` | Underlying fetch or evaluation error |

***

## EsmVersionResolutionError

Thrown when the npm registry cannot resolve a version for the given semver range — including network errors, 404s, and no matching version.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmVersionResolutionError extends InternalMcpError {
  readonly packageName: string;
  readonly range: string;
  readonly originalError?: Error;
}
```

| Property | Type | Description |
| - | - | - |
| `packageName` | `string` | Full package name |
| `range` | `string` | Semver range that failed to resolve (e.g., `^3.0.0`) |
| `originalError` | `Error?` | Underlying registry error |

***

## EsmManifestInvalidError

Thrown when a package's default export does not conform to the `FrontMcpPackageManifest` contract — missing `name`, `version`, or invalid primitive arrays.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmManifestInvalidError extends PublicMcpError {
  readonly packageName: string;
  readonly details?: string;
  readonly mcpErrorCode = -32602; // INVALID_PARAMS
}
```

| Property | Type | Description |
| - | - | - |
| `packageName` | `string` | Full package name |
| `details` | `string?` | Zod validation error details |

***

## EsmCacheError

Thrown when a cache operation (read, write, cleanup) fails — typically due to file system permission issues or disk space.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmCacheError extends InternalMcpError {
  readonly operation: string;
  readonly packageName?: string;
  readonly originalError?: Error;
}
```

| Property | Type | Description |
| - | - | - |
| `operation` | `string` | Cache operation that failed (e.g., `'get'`, `'put'`, `'cleanup'`) |
| `packageName` | `string?` | Package involved in the operation |
| `originalError` | `Error?` | Underlying I/O error |

***

## EsmRegistryAuthError

Thrown when authentication to a private npm registry fails — invalid token, expired credentials, or wrong registry URL.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmRegistryAuthError extends PublicMcpError {
  readonly registryUrl?: string;
  readonly details?: string;
  readonly mcpErrorCode = -32001; // UNAUTHORIZED
}
```

| Property | Type | Description |
| - | - | - |
| `registryUrl` | `string?` | Registry URL that rejected authentication |
| `details` | `string?` | Additional error details |

***

## EsmInvalidSpecifierError

Thrown when a package specifier string is malformed — does not match the expected `@scope/name@range` or `name@range` pattern.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
class EsmInvalidSpecifierError extends PublicMcpError {
  readonly specifier: string;
  readonly mcpErrorCode = -32602; // INVALID_PARAMS
}
```

| Property | Type | Description |
| - | - | - |
| `specifier` | `string` | The invalid specifier string |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.