Error classes

this.fail(new PublicMcpError(message, code?, statusCode?))
throw new InvalidInputError(message?, details?)

Reference

McpError

Every FrontMCP error extends the abstract McpError, itself an Error, except the guard's errors and @frontmcp/auth's internal ones (see below).

PublicMcpError(message, code?, statusCode?, wwwAuthenticate?)

The error to fail with when the model should read the message. code defaults to "PUBLIC_ERROR", and statusCode to 400. wwwAuthenticate is only used on FrontMCP's own HTTP endpoints. Subclass it for errors of your own:

export class TicketArchivedError extends PublicMcpError {
  constructor(id: string) {
    super(`Ticket ${id} is archived. Ask a lead to restore it.`, "TICKET_ARCHIVED", 409);
  }
}

InternalMcpError(message, code?)

An error whose message must not leave the server. code defaults to "INTERNAL_ERROR", and statusCode is 500. Production clients get Internal FrontMCP error. Please contact support with error ID: err_…; the message goes to the log.

What the client receives

From a tool

A tool that fails, with this.fail() or by throwing, answers with a normal result: isError: true, the text, and _meta with errorId, code, timestamp, and in development, stack.

• _meta.code is the error's code. this.fail() passes every McpError through as it is. A thrown error keeps its code too if it's public.
• A thrown error that isn't public is wrapped as ToolExecutionError: code TOOL_EXECUTION_ERROR, text Tool "…" execution failed: and the message. Passed to this.fail(), the same InternalMcpError keeps its code, and a plain Error becomes SERVER_ERROR. See it run.
• The text is getInternalMessage() in development and getPublicMessage() in production. For most public errors they're the same; the few that differ are marked below.
• A few refusals are JSON-RPC errors instead, all before execute() runs: a thrown ToolCredentialsRequiredError (-32001, with data.authUrl); for clients before MCP 2026-07-28, TaskAugmentationNotSupportedError and TaskAugmentationRequiredError (-32601); and under 2026-07-28, a call to a tool with execution.taskSupport: "required" from a client that didn't declare the tasks extension (-32602, Tool "…" runs as a task; declare the io.modelcontextprotocol/tasks extension in clientCapabilities).

From a resource or a prompt

resources/read and prompts/get answer with a JSON-RPC error. Its message is getPublicMessage(), except that an internal error's message is kept in development, and data holds errorId and code. The JSON-RPC code comes from the class:

A thrown error that isn't public is wrapped, as ResourceReadError (Resource "…" read failed: ) or PromptExecutionError (Prompt execution failed: ). See it run.

Before any handler

A few refusals happen before FrontMCP knows what the request is for. They're HTTP errors with a JSON-RPC body, and no error class of yours is involved: throttle.global gives HTTP 429 and -32029, throttle.ipFilter HTTP 403 and -32001 (see Guard options), and, on the Node HTTP server, a body over http.bodyLimit HTTP 413 and -32600, Payload Too Large.

In production

With NODE_ENV=production, a public error's message is sent, and an internal error's is replaced with Internal FrontMCP error. Please contact support with error ID: err_…; InvalidOutputError says Output validation failed. Please contact support. instead. No stack is sent. The Playground runs in development, so the examples below format errors the way production does with createErrorHandler({ isDevelopment: false }).

Errors that aren't McpErrors

• Any other Error, like a TypeError or a driver's error, is internal. Passed to this.fail(), it becomes a GenericServerError, code SERVER_ERROR; in development the text adds Original error: and the stack.
• The guard's errors (ExecutionTimeoutError, ConcurrencyLimitError and the rest) extend GuardError, not McpError. Passed to this.fail(), they keep their code and message, as public errors. Thrown, only ExecutionTimeoutError keeps its code in a tool; the others are wrapped. In a resource or prompt, all of them are wrapped when thrown, like any error that isn't public.
• @frontmcp/auth's internal errors (JwtSecretRequiredError, SessionSecretRequiredError and the rest) extend AuthInternalError. Their own code is lost: clients get SERVER_ERROR.
• AuthorityDeniedError, from @frontmcp/auth, is how authorities refuses a call. Clients get code AUTHORITY_DENIED, and its message is kept in production.

Helper functions

The classes

The tables give each class's code, the JSON-RPC code a resource or prompt gets for it (a tool gets the code in _meta.code, as above), whether its message is kept in production, and who throws it. Unless a table says otherwise, a class's constructor takes what its message needs, in the order the message uses it.

Base classes

Tools and prompts

Resources

Validation

Auth

@frontmcp/sdk also re-exports @frontmcp/auth's internal errors, which FrontMCP throws while starting up or handling tokens. Clients get SERVER_ERROR for all of them, hidden in production; the server log has the real code. The ones you're most likely to meet: JwtSecretRequiredError (JWT_SECRET_REQUIRED: production with auth.mode: "local" and no JWT_SECRET), JwtSecretWeakError (JWT_SECRET_INVALID: a secret under 32 bytes), SessionSecretRequiredError (SESSION_SECRET_REQUIRED), ElicitationSecretRequiredError, TokenNotAvailableError, TokenStoreRequiredError, TokenLeakDetectedError, EncryptionKeyNotConfiguredError, EncryptionContextNotSetError, VaultLoadError, VaultNotFoundError, SessionIdEmptyError, CredentialProviderAlreadyRegisteredError, OrchestratedAuthNotAvailableError, OrchestratorJwksNotAvailableError and NoProviderIdError. AuthProvidersNotConfiguredError, ScopeDeniedError and InMemoryStoreRequiredError are never thrown.

Rate limits and the guard

See Guard options for when each limit trips.

Agents

A client calling an agent gets TOOL_EXECUTION_ERROR when its loop runs out of turns or time, or its model fails; @Agent lists the texts. The exceptions are an answer that doesn't match the agent's outputSchema, which is InvalidOutputError, code INVALID_OUTPUT, as for a tool (in 1.8.5 and 1.8.6 it was TOOL_EXECUTION_ERROR too, with a stack trace in development), and the three agent-to-agent errors above, which keep their codes.

Elicitation and multi-round-trip requests

Tasks

All but the last are public.

Jobs and workflows

Remote apps

Remote servers covers how a remote app fails, and what each failure looks like.

For App.remote(). The public ones tell the model which remote server failed.

The remote errors also have an mcpErrorCode field. FrontMCP doesn't use it for tools/call, resources/read or prompts/get: the JSON-RPC code follows statusCode like any other public error, so a remote "not found" is -32602.

Providers

All internal (-32603, hidden in production), thrown by FrontMCP while building or looking up providers: ProviderNotAvailableError (PROVIDER_NOT_AVAILABLE: what this.get() throws for a provider it can't find), ProviderNotRegisteredError, ProviderNotInstantiatedError, ProviderScopeMismatchError, ProviderScopedAccessError, ProviderConstructionError (Failed to construct provider "…"), ProviderDependencyError, DependencyCycleError (Circular dependency detected: A -> B -> A), InvalidDependencyScopeError, PluginDependencyError, InvalidPluginScopeError and DependencyNotFoundError.

Registries, decorators and normalization

All internal, thrown by FrontMCP, most of them while the server starts:

• Registries: DuplicateAppIdError (DUPLICATE_APP_ID, Two apps share the id "status": …, for two App.remote() or App.esm() apps with one id; new in 1.9.3), RegistryDefinitionNotFoundError, RegistryGraphEntryNotFoundError, RegistryDependencyNotRegisteredError (Tool "X" depends on "Db", which is not registered), InvalidRegistryKindError, NameDisambiguationError, EntryValidationError, FlowNotRegisteredError, UnsupportedHookOwnerKindError, InvalidHookFlowError and RegistryNotInitializedError.
• Decorators: InvalidDecoratorMetadataError (@FrontMcp invalid metadata for "apps": …, see @FrontMcp) and HookTargetNotDefinedError.
• Normalization, for an entry in a providers, plugins, tools or other list that isn't what FrontMCP expects: MissingProvideError, InvalidUseClassError, InvalidUseFactoryError, InvalidUseValueError and InvalidEntityError (Invalid Tool 'X'. Expected a class or function.).

Transport

Internal, thrown by FrontMCP's transports: MethodNotImplementedError, UnsupportedTransportTypeError, InvalidTransportSessionError, TransportNotConnectedError, TransportAlreadyStartedError, TransportServiceNotAvailableError and SessionClaimConflictError. TransportBusRequiredError is never thrown. Two are public: UnsupportedContentTypeError (UNSUPPORTED_CONTENT_TYPE, for an older client's SSE message with the wrong content type) and PayloadTooLargeError (PAYLOAD_TOO_LARGE, HTTP 413).

ESM packages

Loading apps from npm covers how a package fails to load. For an App.esm() package, FrontMCP throws these while the server starts, so each one stops it:

Changed in 1.9.2: before, these were exported but never thrown, and a package that failed to load failed with a plain Error.

Since 1.9.1, for a single tool, resource or prompt loaded with Tool.esm(), Tool.remote() and the like: ExternalEntryLoadError, when its package doesn't load or its server can't be reached, ExternalEntryNotFoundError, when the package or server has no entry by that name, and ExternalEntryNotSupportedError, for an agent, skill or job loaded that way, which FrontMCP refuses. All three stop the server from starting.

Everything else

Internal, thrown by FrontMCP: FlowExitedWithoutOutputError (Flow exited without producing output: a tool's execute() returned undefined), RequestContextNotAvailableError (this.context used outside a request), ContextExtensionNotAvailableError, ServerNotFoundError, ConfigNotFoundError, RequiredConfigUndefinedError, SessionVerificationFailedError, ScopeConfigurationError, HaConfigurationError, InvokeStateMissingKeyError, FlowInputMissingError, DynamicAdapterNameError, ServerlessHandlerNotInitializedError, VercelKvNotSupportedError, the skill errors InvalidSkillError, SkillInstructionFetchError, InvalidInstructionSourceError, SkillSessionError and SkillContextNotImplementedError, the agent errors AgentConfigKeyNotFoundError, AgentToolExecutionError and AgentMethodNotAvailableError, and ToolNameConflictError, for a tool added with registerTool() under a name the server already has (new in 1.9). SkillValidationError is public: it stops the server from starting when a skill with toolValidation: "strict" names a tool the server doesn't have (Skill '…' failed tool validation: missing tools […], since 1.9; see @Skill). GlobalConfigNotFoundError (Plugin "cache" requires global "redis" configuration) is public, and so is UnenforcedMetadataError (UNENFORCED_METADATA), which stops the server from starting when an entry declares a plugin's option, like approval, and no plugin that enforces it covers the entry: see @Plugin. VercelKvAsyncInitRequiredError and EnclaveExecutionError are never thrown.

FlowControl isn't an error to report: it's how this.fail() and this.respond() end a call, and its message is empty. See A tool call succeeds after this.fail().

Caveats

• Fail with a public class for anything the model should read. PublicMcpError, or one of InvalidInputError, RateLimitError, QuotaExceededError, UnauthorizedError and ResourceNotFoundError, or a subclass of your own.
• Throwing and failing differ only for errors that aren't public: TOOL_EXECUTION_ERROR when thrown, the error's own code through this.fail(). Production hides both.
• In a resource or prompt, statusCode picks the JSON-RPC code. A PublicMcpError with status 404 is -32602, like any other client error; 401 and 403 are the ones that change it.
• A development client reads more than a production one: the stack, an internal error's message, and for a few classes, a longer developer message. Test what production sends with createErrorHandler({ isDevelopment: false }).
• Many exported classes are never thrown in 1.9.3, as the tables say. Don't wait for them in a client.

Usage

Failing with a built-in class

Each sample below is a class you might fail a tool with. fail_with fails with the one you name; the test checks what a client reads for each, in development. Try other samples in the Call tab.

import {
  ConcurrencyLimitError,
  ElicitationDisabledError,
  InternalMcpError,
  InvalidInputError,
  PublicMcpError,
  QuotaExceededError,
  RateLimitError,
  SessionSecretRequiredError,
  UnauthorizedError,
} from "@frontmcp/sdk";

export const samples: Record<string, Error> = {
  public: new PublicMcpError("There's no ticket T-9."),
  publicWithCode: new PublicMcpError("Ticket T-2 is archived. Ask a lead to restore it.", "TICKET_ARCHIVED", 409),
  invalidInput: new InvalidInputError("`due` must be in the future.", { field: "due" }),
  rateLimit: new RateLimitError(3600),
  quota: new QuotaExceededError("export"),
  unauthorized: new UnauthorizedError("Sign in again to export tickets."),
  internal: new InternalMcpError("replica lag 12s on tickets-db-2", "DB_LAG"),
  plain: new Error("connect ECONNREFUSED 10.0.4.12:5432"),
  guard: new ConcurrencyLimitError("export_tickets", 1),
  elicitationOff: new ElicitationDisabledError(),
  authInternal: new SessionSecretRequiredError("sessions"),
};

What production sends

The same samples, formatted by an ErrorHandler with isDevelopment: false, which is what tools/call uses when NODE_ENV=production. Public errors keep their message; internal ones, plain errors and @frontmcp/auth's errors become an error ID; ElicitationDisabledError switches to its shorter message:

import { test, expect } from "@frontmcp/testing";
import { createErrorHandler, isPublicError, toMcpError } from "@frontmcp/sdk";
import { samples } from "./samples";

const production = createErrorHandler({ isDevelopment: false });
const hidden = /^Internal FrontMCP error\. Please contact support with error ID: err_[0-9a-f]{16}$/;

const expected: Record<string, [code: string, text: string | RegExp]> = {
  public: ["PUBLIC_ERROR", "There's no ticket T-9."],
  invalidInput: ["INVALID_INPUT", '`due` must be in the future.\nDetails: {\n  "field": "due"\n}'],
  rateLimit: ["RATE_LIMIT_EXCEEDED", "Rate limit exceeded. Retry after 3600 seconds"],
  guard: ["CONCURRENCY_LIMIT", 'Concurrency limit reached for "export_tickets" (max: 1)'],
  elicitationOff: ["ELICITATION_DISABLED", "Elicitation is disabled on this server."],
  internal: ["DB_LAG", hidden],
  plain: ["SERVER_ERROR", hidden],
  authInternal: ["SERVER_ERROR", hidden],
};

for (const [sample, [code, text]] of Object.entries(expected)) {
  test(`${sample} in production`, () => {
    const result = production.handle(samples[sample]);
    expect(result._meta?.code).toBe(code);
    if (typeof text === "string") expect(result.content[0].text).toBe(text);
    else expect(result.content[0].text).toMatch(text);
    expect(result._meta).not.toHaveProperty("stack");
  });
}

test("the error ID is the one in the server's log", () => {
  const result = production.handle(samples.internal);
  expect(result._meta?.errorId).toBe((samples.internal as { errorId?: string }).errorId);
});

test("guard errors aren't McpErrors, but are sent as public ones", () => {
  expect(isPublicError(samples.guard)).toBe(false);
  expect(toMcpError(samples.guard)).toMatchObject({ code: "CONCURRENCY_LIMIT", isPublic: true });
});

Failing vs throwing

A public error reads the same thrown or failed. The others don't: thrown from a tool's execute(), an InternalMcpError or a guard error other than a timeout is wrapped as TOOL_EXECUTION_ERROR, and a ToolCredentialsRequiredError becomes a JSON-RPC error rather than a tool result. Thrown from a resource, every guard error is wrapped, the timeout too:

import {
  ConcurrencyLimitError,
  ExecutionTimeoutError,
  InternalMcpError,
  PublicMcpError,
  ResourceContext,
  ResourceTemplate,
  Tool,
  ToolContext,
  ToolCredentialsRequiredError,
  z,
} from "@frontmcp/sdk";

const make: Record<string, () => Error> = {
  public: () => new PublicMcpError("There's no ticket T-9.", "TICKET_NOT_FOUND", 404),
  internal: () => new InternalMcpError("replica lag 12s", "DB_LAG"),
  concurrency: () => new ConcurrencyLimitError("export", 1),
  timeout: () => new ExecutionTimeoutError("export", 500),
  credentials: () => new ToolCredentialsRequiredError({ toolId: "sync_crm", providers: ["crm"], authUrl: "https://desk.example.com/connect/crm" }),
};

const input = { sample: z.enum(["public", "internal", "concurrency", "timeout", "credentials"]) };
type Input = { sample: "public" | "internal" | "concurrency" | "timeout" | "credentials" };

@Tool({ name: "throw_it", description: "Throw a sample error", inputSchema: input })
export class ThrowIt extends ToolContext {
  async execute({ sample }: Input): Promise<{ ok: boolean }> {
    throw make[sample]();
  }
}

@Tool({ name: "fail_it", description: "Fail with a sample error", inputSchema: input })
export class FailIt extends ToolContext {
  async execute({ sample }: Input): Promise<{ ok: boolean }> {
    this.fail(make[sample]());
  }
}

@ResourceTemplate({ name: "thrown", uriTemplate: "thrown://{sample}", mimeType: "text/plain" })
export class Thrown extends ResourceContext<{ sample: string }> {
  async execute(uri: string, { sample }: { sample: string }): Promise<{ contents: { uri: string; text: string }[] }> {
    throw make[sample]();
  }
}

Failing in a resource or a prompt

In a resource or a prompt, the class's statusCode picks the JSON-RPC code. TicketLockedError is a public error of this server's own, with status 403:

import { InternalMcpError, PublicMcpError, ResourceContext, ResourceNotFoundError, ResourceTemplate, UnauthorizedError } from "@frontmcp/sdk";

export class TicketLockedError extends PublicMcpError {
  constructor(id: string) {
    super(`Ticket ${id} is under legal hold.`, "TICKET_LOCKED", 403);
  }
}

@ResourceTemplate({ name: "ticket", uriTemplate: "tickets://{id}", mimeType: "application/json" })
export class Ticket extends ResourceContext<{ id: string }> {
  async execute(uri: string, { id }: { id: string }) {
    if (id === "T-3") this.fail(new TicketLockedError(id));
    if (id === "T-4") this.fail(new UnauthorizedError("Sign in to read archived tickets."));
    if (id === "T-5") this.fail(new PublicMcpError("The ticket store is down for maintenance.", "STORE_DOWN", 503));
    if (id === "T-6") this.fail(new InternalMcpError("replica lag 12s", "DB_LAG"));
    if (id !== "T-1") this.fail(new ResourceNotFoundError(uri));
    return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ id, title: "Cannot log in" }) }] };
  }
}

Errors FrontMCP raises for you

Most errors a client sees come from FrontMCP, before or around your code. Here each test makes FrontMCP raise one:

import { App, FrontMcp, Job, JobContext, Prompt, PromptContext, Resource, ResourceContext, Tool, ToolContext, z } from "@frontmcp/sdk";

@Tool({ name: "search_tickets", description: "Search tickets by title", inputSchema: { query: z.string().min(1) } })
class SearchTickets extends ToolContext {
  async execute({ query }: { query: string }) {
    return { query, tickets: [] };
  }
}

@Tool({ name: "close_ticket", description: "Close a ticket", inputSchema: { id: z.string() }, authorities: "admin" })
class CloseTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    return { id, closed: true };
  }
}

@Tool({ name: "run_on_deno", description: "Only on Deno", inputSchema: {}, availableWhen: { runtime: ["deno"] } })
class RunOnDeno extends ToolContext {
  async execute() {
    return { ok: true };
  }
}

@Tool({ name: "export_archive", description: "Export the ticket archive", inputSchema: {}, execution: { taskSupport: "required" } })
class ExportArchive extends ToolContext {
  async execute() {
    return { rows: 18_000 };
  }
}

@Prompt({ name: "summarize_ticket", description: "Summarize a ticket", arguments: [{ name: "id", required: true }] })
class SummarizeTicket extends PromptContext {
  async execute({ id }: Record<string, string>) {
    return { messages: [{ role: "user" as const, content: { type: "text" as const, text: `Summarize ticket ${id}.` } }] };
  }
}

@Resource({ name: "audit-log", uri: "desk://audit-log", mimeType: "text/plain", authorities: "admin" })
class AuditLog extends ResourceContext {
  async execute(uri: string) {
    return { contents: [{ uri, text: "T-1 closed by nour" }] };
  }
}

@Resource({ name: "deploy-notes", uri: "desk://deploy-notes", mimeType: "text/plain", availableWhen: { runtime: ["deno"] } })
class DeployNotes extends ResourceContext {
  async execute(uri: string) {
    return { contents: [{ uri, text: "Deploy with deployctl." }] };
  }
}

@Job({ name: "nightly_cleanup", description: "Close stale tickets", inputSchema: {}, outputSchema: {} })
class NightlyCleanup extends JobContext {
  async execute() {
    return {};
  }
}

@App({
  id: "help-desk",
  name: "Help Desk",
  tools: [SearchTickets, CloseTicket, RunOnDeno, ExportArchive],
  resources: [AuditLog, DeployNotes],
  prompts: [SummarizeTicket],
  jobs: [NightlyCleanup],
})
class HelpDeskApp {}

@FrontMcp({
  info: { name: "help-desk", version: "1.0.0" },
  apps: [HelpDeskApp],
  authorities: { profiles: { admin: { roles: { any: ["admin"] } } } },
})
export default class Server {}

ENTRY_UNAVAILABLE's message lists the server's OS, runtime and deployment, in production too, for tools, resources and prompts alike. If that's more than callers should know, leave the entry out of the server instead of relying on availableWhen.

Troubleshooting

Internal FrontMCP error. Please contact support with error ID: err_…

The server runs with NODE_ENV=production, and the call failed with an internal error: an InternalMcpError or one of FrontMCP's, a plain Error, or one of @frontmcp/auth's. Search the server's log for the error ID: FrontMCP logs the original message and stack with it. If the model should read the message, fail with a public class. See this.fail.

My error's code arrives as TOOL_EXECUTION_ERROR

It was thrown from execute() and isn't public: an InternalMcpError, a guard error, or an Error with a code property of its own. Throw a PublicMcpError subclass, or pass the error to this.fail(), which keeps an McpError's code. See Failing vs throwing.

My error's code arrives as SERVER_ERROR

It isn't an McpError: a plain Error, or one of @frontmcp/auth's internal errors, passed to this.fail(). Only McpErrors and guard errors keep their code. Wrap it: this.fail(new InternalMcpError(error.message, "CRM_SYNC_FAILED")) keeps the message out of production, with a code clients can tell apart.

A resource error arrives as -32602 when I meant "not found"

Under MCP 2026-07-28, every client error from a resource is -32602, including ResourceNotFoundError; -32002 is only for older clients. Tell errors apart by data.code, which is your class's code. ResourceNotFoundError is the exception: its data is { uri }, so check the message.

The client sees a long developer message, like Elicitation is disabled in server configuration. Enable it via …

In development, a tool's error text is the internal message, written for you. Production sends the public one: here, Elicitation is disabled on this server. Resources and prompts send the public one in both. See What production sends.

I'm waiting for AgentLoopExceededError (or QuotaExceededError, SessionMissingError, an ESM error…) and it never comes

FrontMCP 1.9.3 exports these classes but never throws them. The tables say which, and what's thrown instead, like TOOL_EXECUTION_ERROR for an agent that runs out of turns.