API Errors

Overview

Error handling in @cyanheads/mcp-ts-core follows a strict layered pattern: tool and resource handlers throw McpError freely (no try/catch), the handler factory catches and normalizes all errors, and services use ErrorHandler.tryCatch for structured logging and wrapping.

Imports:

import { notFound, validationError, McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
import { ErrorHandler } from '@cyanheads/mcp-ts-core/utils';

Type-Driven Error Contract (recommended)

The recommended path for new tools and resources. Declare failure modes as a const tuple under errors; the reason union flows into the handler's ctx.fail and TypeScript enforces that you can only fail with a declared reason:

import { tool, z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

export const fetchTool = tool('fetch_articles', {
  description: 'Fetch articles by PMID',
  input: z.object({ pmids: z.array(z.string()).describe('PMIDs') }),
  output: z.object({ articles: z.array(z.unknown()).describe('Articles') }),

  errors: [
    { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
      when: 'No requested PMID returned data',
      recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
    { reason: 'queue_full', code: JsonRpcErrorCode.RateLimited,
      when: 'Local request queue is at capacity', retryable: true,
      recovery: 'Wait 30 seconds and retry, or reduce batch size.' },
    { reason: 'ncbi_down', code: JsonRpcErrorCode.ServiceUnavailable,
      when: 'NCBI E-utilities unreachable after retries', retryable: true,
      recovery: 'NCBI is degraded; retry in a few minutes.' },
  ],

  async handler(input, ctx) {
    const articles = await ncbi.fetch(input.pmids);
    if (articles.length === 0) {
      throw ctx.fail('no_match', `None of ${input.pmids.length} PMIDs returned data`);
    }
    // ctx.fail('typo')   ← TypeScript error: 'typo' isn't in the contract
    return { articles };
  },
});

What you get:

recovery is the wire default for its reason. The contract recovery is required metadata documenting the agent's next move when this failure mode fires (a forcing function for thoughtful guidance — placeholders like "Try again." get flagged by the linter), and it is what the caller receives. When a failure whose data.reason names a declared entry reaches the tool or resource handler factory with no data.recovery, the factory sets data.recovery.hint to that entry's recovery before it logs the failure and builds the envelope, so the Error in tool:<name> record, structuredContent.error.data, and the Recovery: line in content[] carry the same hint. It matches on the reason alone — a bare ctx.fail('reason'), a service throwing notFound(msg, { reason }), and a declared reason raised through a factory with a different code all get it. A throw-site recovery always wins, whatever its shape. An undeclared reason, a tool without errors[], a non-McpError throw, and a cancelled call get nothing, and the framework-owned invalid_arguments / client_capability_missing refusals keep their own hints. The thrown McpError is never changed — a handler-level test of ctx.fail sees exactly what the throw site wrote — and runToolContract applies the same fill, so a contract test sees the production envelope. Prompts declare no contract.

export const calculateTool = tool('calculate', {
  // ...
  errors: [
    { reason: 'empty_expression', code: JsonRpcErrorCode.ValidationError,
      when: 'Expression is empty or whitespace-only.',
      recovery: 'Provide a non-empty mathematical expression to evaluate.' },
  ],
  handler(input, ctx) {
    if (!input.expression.trim()) {
      // Static recovery — the framework fills the contract's hint onto the wire.
      throw ctx.fail('empty_expression');
    }
    // ...
  },
});

Same for a service, which needs no ctx to get the hint — the reason is enough:

export class MathService {
  parse(expr: string) {
    try {
      return mathjs.parse(expr);
    } catch (err) {
      throw validationError(`Parse failed: ${err.message}`, { reason: 'parse_failed' });
    }
  }
}

The contract is the single source of truth — write the recovery once, lint validates ≥5 words, and the framework carries it to every failure with that reason. For runtime-context recovery (interpolating input values, attempted IDs, queue state), override at the throw site:

throw ctx.fail('no_match', `No item ${id}`, {
  recovery: { hint: `No item ${id}; try IDs 1-100 instead.` },
});

A recovery hint names a capability, never an internal method. The reader is a model whose only reachable surface is this server's tool names — it cannot call a TypeScript method, set a library option, or re-run an internal function. Re-stage the table via registerTable() is unfollowable and invites a hallucinated tool call; Re-run the tool that produced this table to stage it again, or list the currently staged tables with this server's dataframe-describe tool is actionable from where the reader sits. Name a condition the caller cannot observe — an option flag they never set — and the hint is noise for the same reason. The framework holds its own throws to this rule: the canvas SQL gate's rejections point at the dataframe-query and dataframe-describe capabilities rather than the provider methods behind them.

ctx.recoveryFor — the entry's hint at the throw site

ctx.recoveryFor(reason) returns { recovery: { hint: <contract.recovery> } } for a declared reason, ready to spread into data. Always available on Context (returns {} when no contract is attached or the reason is unknown — spread-safe with no optional chaining). On HandlerContext<R> it tightens to a typed signature constrained to the declared reason union.

It is not needed to put a declared hint on the wire — the fill above does that. Reach for it when the hint has to ride the thrown error itself: a test asserting data.recovery on the handler's own throw, or a site that deliberately sends another entry's guidance (ctx.fail('a', msg, ctx.recoveryFor('b'))), which the fill respects as authored.

severity — log a modeled outcome below error

An outcome a tool declares in errors[] is a modeled result, not an incident. A caller who answers no to a confirmation prompt, a lookup whose miss is an ordinary answer — logging those at error alongside upstream faults and bugs leaves the error stream unreadable at the level log-based alerting works on. severity moves that one record's level:

errors: [
  { reason: 'consent_declined', code: JsonRpcErrorCode.InvalidRequest,
    when: 'The caller declined the confirmation prompt.', severity: 'notice',
    recovery: 'Re-run the tool and confirm the prompt to proceed with the change.' },
],

Values are the logger's own level names below error — debug, info, notice, warning. Omitting the field keeps error, byte for byte, for every server that does not opt in.

Tools only. Resolution happens in the tool handler factory, against the thrown error's data.reason — the same reason-to-entry lookup that fills data.recovery. Resources declare errors[] but write no failure record, so the field is accepted there and inert. A reason thrown below the handler that the contract never declared, an entry with no severity, and a non-McpError throw all keep error. A cancelled request keeps its own info, stack-free path regardless.

The framework's own refusals log at notice. An argument rejection (invalid_arguments, raised only by the schema gate before the handler runs) and a ctx.requestInput the connection cannot serve (client_capability_missing) are routine caller or connection traffic, not server faults, so their Error in tool:<name> record — and the failure-payload record when LOG_TOOL_FAILURE_PAYLOADS=true — is emitted at notice, and mcp.errors.classified counts them with mcp.error.severity: "notice". Nothing to declare; an errors[] entry naming either reason with its own severity still wins. The wire envelope and mcp.tool.rejections are unchanged, and a schema that wrongly rejects valid calls still shows per tool on mcp.tool.rejections.

Skip the contract for one-off internal tools or quick prototypes — ctx is plain Context (no fail) and you throw via factories directly. Behavior is identical at the wire; the contract just adds compile-time safety.

Declare contracts inline on each tool, even when similar across tools. The contract is part of the tool's documented public surface — reading one tool definition file should give the full picture (input, output, errors, handler, format). Don't extract a shared errors[] constant or contract module to deduplicate near-identical entries; per-tool repetition is the intended cost of locality, and dynamic recovery hints often need tool-specific runtime context anyway. If a code-cleanup pass suggests consolidating contracts, decline — the duplication is load-bearing for tool-def readability.

Limits of the conformance lint. The conformance and prefer-fail rules scan the handler's source text for throw statements. Errors thrown from called services (e.g. await myService.fetch() raising RateLimited internally) are invisible — the lint only sees what's lexically in the handler. Treat the contract as the advertised failure surface; bubbled-up codes still reach the client correctly via the auto-classifier, just without lint enforcement.

Carrying contract reason from services

Services don't receive ctx automatically (unlike handlers), so they can't call ctx.fail directly — though ctx can be passed as a parameter when needed. To make a service-thrown failure carry the contract's reason on the wire, pass data: { reason: 'X' } to the factory. The framework's auto-classifier preserves data unchanged, so clients see the same error.data.reason they'd see from ctx.fail:

// my-service.ts
throw validationError('Expression cannot be empty.',  { reason: 'empty_expression' });
throw serviceUnavailable('Upstream timeout',          { reason: 'evaluation_timeout' });

// my-tool.tool.ts
errors: [
  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,
    when: 'Input is empty.',
    recovery: 'Provide a non-empty expression to evaluate.' },
  { reason: 'evaluation_timeout', code: JsonRpcErrorCode.ServiceUnavailable,
    when: 'Upstream exceeded the configured timeout.',
    recovery: 'Simplify the expression or retry the request after a brief delay.' },
]

The handler doesn't catch and re-throw — letting service errors bubble unchanged keeps "logic throws, framework catches" intact. The wire payload carries code, data.reason, and the declared entry's recovery as data.recovery.hint (filled at the handler boundary, whatever code the service picked), so clients can switch on reason without parsing message text. What's lost is lint-time enforcement that every reason is reachable; compensate with one wire-shape test per reason.

Mark the entries the service produces. error-contract-unthrown reads the handler body alone, so in a handler that mixes one local precondition with service-thrown reasons it flags each service reason as dead. Add thrownBy: 'service' to those entries:

errors: [
  { reason: 'empty_expression',   code: JsonRpcErrorCode.ValidationError,
    when: 'Input is empty.',
    recovery: 'Provide a non-empty expression to evaluate.',
    thrownBy: 'service' },
]

The field is lint-only metadata — nothing at runtime reads it, so the entry is typed, advertised, and thrown exactly as an unmarked one (its recovery filled like any other), and its reason stays in the ctx.fail / ctx.recoveryFor union. It suppresses the one rule that cannot see below the handler, and only for the entries it marks; the handler's own reasons keep being checked.

When not to throw

Throw when the server has authoritative classification — auth failure, rate limit, schema violation, upstream 5xx, missing required input. Don't throw when "this looks wrong" depends on intent the server can't see. For mutators, surface raw pre- and post-mutation observable state in the response and let the agent decide whether it matches intent — the server can detect that the file shrunk, but only the agent knows whether it was supposed to. Tell: defensive code justified as a free rider on other work — audit it standalone, and it usually doesn't earn its keep.

A best-effort call that catches and degrades must still rethrow on ctx.signal?.aborted: catch (err) { if (ctx.signal?.aborted) throw err; return degraded(); }. One example is an enrichment lookup whose failure should return the primary result with a notice. The factory maps a cancelled handler to RequestCancelled only when the handler throws. A catch-all degrade turns the caller's cancellation into a "successful" response and logs a false failure warning.

Error Factories (fallback)

Use when no contract entry fits — ad-hoc throws, tools without a contract, or service-layer code. Shorter than new McpError(...) and self-documenting. All return McpError instances and accept an optional options parameter for error chaining via { cause }.

throw notFound('Item not found', { itemId: '123' });
throw validationError('Missing required field: name', { field: 'name' });
throw unauthorized('Token expired');

// With cause for error chaining
throw serviceUnavailable('API call failed', { url }, { cause: error });

Available factories:

options is { cause?: unknown } — the standard ES2022 ErrorOptions type.

McpError Constructor

For codes not covered by factories (rare — MethodNotFound, ParseError, InitializationFailed, UnknownError):

throw new McpError(code, message?, data?, options?)

• code — a JsonRpcErrorCode enum value
• message — optional human-readable description of the failure
• data — optional structured data (plain object), returned to the client verbatim. Pass the explicit fields the caller acts on (the rejected key, a limit, a reason), never ctx or another request context: a handler ctx carries request metadata and, after an elicitation round, what the user typed. Framework helpers follow the same rule — a storage, parser, or formatter failure carries only its offending field or a reason, whatever context you pass them.
• options — optional { cause?: unknown } for error chaining

Example:

import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';

throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection pool exhausted', {
  pool: 'primary',
});

Error Codes

Standard JSON-RPC 2.0 codes:

Implementation-defined codes (-32000 to -32099):

Auto-Classification

When a handler throws a plain Error (or any non-McpError value), the framework classifies it to the most specific JsonRpcErrorCode automatically. This matters when you don't control what a third-party library throws and can't predict its error type.

Use factories or McpError directly when the code must be exact — auto-classification is best-effort pattern matching and not guaranteed for ambiguous messages. For errors from your own code where the code matters, be explicit.

Resolution Order

The framework applies these steps in order — first match wins:

1. Request signal aborted — ctx.signal.aborted is true when the handler unwinds → RequestCancelled. Resolved before the thrown value is classified at all — by the tool and resource handler factories, and by the HTTP transport's error handler against the inbound request's signal, which catches a caller that hangs up before any handler runs (mid-body, say) and answers it 499 — so it outranks every step below, McpError included: the caller withdrew the request, and what the handler threw on the way out does not change that. Covers every shape an abort leaves behind — a notifications/cancelled reason string, the DOMException named AbortError a reason-less cancellation produces, a service's own McpError, and the SDK's SdkError(ConnectionClosed) on transport close. The accepted cost is that an unrelated fault raised after the abort is recorded as a cancellation too; it is bounded, because the SDK writes no response for a request whose signal it aborted. A handler that throws while the signal is live is untouched by this step.
2. McpError instance — error.code is preserved as-is; no classification needed.
3. SDK transport-closed rejection — an SdkError carrying SdkErrorCode.ConnectionClosed → RequestCancelled. The SDK rejects every in-flight request when the transport closes, which is what a client disconnect looks like from inside a handler. Matched on the code, not the message: one of its wordings says "aborted" and would otherwise be caught by the generic abort pattern in step 7 and read as a Timeout. Still the rule for a throw raised where no request signal is in scope — a service, an outbound leg, a background task.
4. Engine resource limit — a RangeError whose whole message is one the engine raises when it runs out of a resource → InternalError: Maximum call stack size exceeded (JavaScriptCore adds a trailing period) and the maximum string size (V8 Invalid string length, JavaScriptCore Out of memory). A handler that recurses without bound names nothing a caller can change, so it is a server fault. Every other RangeError — new Array(-1), (1).toFixed(101), an invalid date, 1n / 0n, or one whose message merely contains a limit text — continues to step 5.
5. JS constructor name — matched against a fixed table (e.g. ZodError → ValidationError, SyntaxError → ValidationError). Note: TypeError is intentionally excluded — runtime TypeErrors are programmer errors, not validation failures.
6. Provider-specific patterns — HTTP status codes, AWS exception names, Supabase, OpenRouter. Checked before common patterns because they are more specific (e.g. status code 429 beats the generic rate limit pattern).
7. Common message/name patterns — broad keyword patterns covering auth, not-found, validation, etc. First match wins; order matters.
8. AbortError name — error.name === 'AbortError' → Timeout.
9. Fallback — InternalError.

However it is reached, a RequestCancelled is logged at info with no stack — neither the thrown value's own nor one reached through its cause chain. Step 1 settles the completion log too, which carries metrics.errorCode: "-32011" alongside isSuccess: false; a raw SdkError that reaches the code through step 3 alone is not an McpError, so that log still reads UNHANDLED_ERROR.

The code this ladder picks is the one the caller receives, and it is also the origin every error counter records: mcp.tool.error_category, mcp.prompt.error_category, and mcp.error.category on mcp.errors.classified all bucket that same code, so a plain Error('Request timed out') files as upstream everywhere, never server on one counter and upstream on another. See api-telemetry's Error category.

The framework's own output-contract parses are not caller errors. A result that breaks the definition's output schema (tools and resources) or its enrichment block fails as InternalError (-32603), with a message naming the definition and the contract — Tool my_tool returned output that does not match its output schema: items.0.id: … — and no data. It is the handler's bug, so it files as server, not the ValidationError a raw ZodError would get. A ZodError the handler throws from its own validation keeps ValidationError.

JS Constructor Name Mappings

TypeError is intentionally excluded from the constructor table — runtime TypeErrors (e.g. "Cannot read property X of undefined") are programmer errors, not validation failures. They fall through to message-pattern matching, then to the InternalError fallback.

Common Message Patterns

Patterns are tested against both the error message and name, case-insensitively. First match wins.

Provider-Specific Patterns

Checked before common patterns. Cover: AWS exception names, HTTP status codes, DB connection/constraint errors, Supabase JWT/RLS, OpenRouter/LLM quota errors, and low-level network errors.

Where Errors Are Handled