ESM Errors

Error classes thrown during ESM package loading. Import them from @frontmcp/sdk:

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.

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.

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.

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.

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.

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.

class EsmInvalidSpecifierError extends PublicMcpError {
  readonly specifier: string;
  readonly mcpErrorCode = -32602; // INVALID_PARAMS
}

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

Decorators

API

Errors

Overview

EsmPackageLoadError

EsmVersionResolutionError

EsmManifestInvalidError

EsmCacheError

EsmRegistryAuthError

EsmInvalidSpecifierError

​Overview

​EsmPackageLoadError

​EsmVersionResolutionError

​EsmManifestInvalidError

​EsmCacheError

​EsmRegistryAuthError

​EsmInvalidSpecifierError

Overview

EsmPackageLoadError

EsmVersionResolutionError

EsmManifestInvalidError

EsmCacheError

EsmRegistryAuthError

EsmInvalidSpecifierError