AbortSignal cancellation throws `SdkErrorCode.RequestTimeout` instead of a distinct abort error

[sakthiveltofficial]

Describe the bug
When you cancel a request using AbortSignal, the error you get back has code: 'REQUEST_TIMEOUT' — the same code as an actual timeout. There's no way to tell them apart.

I had logic like this in my app:

if (error.code === SdkErrorCode.RequestTimeout) {
  showRetryMessage(); // was also firing on manual user cancellation
}

Both a real timeout and a deliberate controller.abort() hit the same fallback in cancel() inside protocol.ts (line ~910), which unconditionally wraps any non-SdkError reason as SdkErrorCode.RequestTimeout.

To Reproduce

import { Client } from '@modelcontextprotocol/client';
import { Server } from '@modelcontextprotocol/server';
import { InMemoryTransport, SdkError, SdkErrorCode } from '@modelcontextprotocol/core';

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
const server = new Server({ name: 'test-server', version: '1.0' });
const client = new Client({ name: 'test-client', version: '1.0' });

// handler that hangs until cancelled
server.setRequestHandler('ping', async (_req, ctx) => {
  await new Promise<void>((_, reject) => {
    ctx.mcpReq.signal.addEventListener('abort', () => reject(new Error('cancelled')));
  });
  return {};
});

await server.connect(serverTransport);
await client.connect(clientTransport);

const controller = new AbortController();

// abort at 30ms — timeout is 60s, so it is definitely not the timeout firing
setTimeout(() => controller.abort(new DOMException('User cancelled', 'AbortError')), 30);

try {
  await client.request({ method: 'ping' }, { signal: controller.signal, timeout: 60_000 });
} catch (error) {
  if (error instanceof SdkError) {
    console.log(error.code); // REQUEST_TIMEOUT ← should be something like REQUEST_ABORTED
  }
}

Or run the repro test directly:

pnpm --filter "@modelcontextprotocol/test-integration" test -- test/bug-repros/bug1-abort-signal.test.ts

Expected behavior
Aborting via AbortSignal should produce a distinct error code (e.g. REQUEST_ABORTED) so callers can tell it apart from a real timeout. The timeout path already explicitly passes a typed SdkError — only the abort path falls through to the generic RequestTimeout fallback.

Logs

Caught error code: "REQUEST_TIMEOUT"
Caught error msg : "AbortError: User cancelled the request"

FAIL  test/bug-repros/bug1-abort-signal.test.ts
AssertionError:
  expected 'REQUEST_TIMEOUT' not to be 'REQUEST_TIMEOUT'

Additional context

Root cause is in packages/core/src/shared/protocol.ts around line 910:

const cancel = (reason: unknown) => {
  const error = reason instanceof SdkError
    ? reason
    : new SdkError(SdkErrorCode.RequestTimeout, String(reason)); // ← always RequestTimeout
  reject(error);
};

Quick fix would be adding RequestAborted = 'REQUEST_ABORTED' to SdkErrorCode and checking the reason type in cancel():

let error: SdkError;
if (reason instanceof SdkError) {
  error = reason;
} else if (reason instanceof DOMException && reason.name === 'AbortError') {
  error = new SdkError(SdkErrorCode.RequestAborted, reason.message);
} else {
  error = new SdkError(SdkErrorCode.RequestAborted, String(reason));
}
reject(error);

[sakthiveltofficial]

I'd like to fix this — could you assign this issue to me?

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For AbortSignal cancellation throws timeout instead of abort error, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.

[mcp-claude]

confirmed on main (3834921) and origin/v1.x (69749aa). the cancel() fallback wraps any non-SdkError reason as SdkErrorCode.RequestTimeout, and the abort handler at protocol.ts:1550 (onAbort = () => cancel(options?.signal?.reason)) feeds AbortSignal.reason straight into that fallback — so a user abort is indistinguishable from a real timeout. the same wrap is mirrored at three other sites (protocol.ts pre-abort check, client _serveFromCache, client.listen() pre-abort), so a fix has to touch all four to keep abort semantics consistent across the wire, cache, and listen paths.

workaround for callers today: check options.signal.aborted before reading error.code, or gate on your own AbortController instance.

repro

// repro.ts — run from repo root: npx tsx repro.ts
import { Protocol } from './packages/core-internal/src/shared/protocol';
import type { BaseContext } from './packages/core-internal/src/shared/protocol';
import { SdkError, SdkErrorCode } from './packages/core-internal/src/errors/sdkErrors';
import { InMemoryTransport } from './packages/core-internal/src/util/inMemory';

class TestProtocol extends Protocol<BaseContext> {
    protected assertCapabilityForMethod(): void {}
    protected assertNotificationCapability(): void {}
    protected assertRequestHandlerCapability(): void {}
    protected buildContext(ctx: BaseContext): BaseContext { return ctx; }
}

async function main() {
    const [clientTransport] = InMemoryTransport.createLinkedPair();
    const protocol = new TestProtocol();
    await protocol.connect(clientTransport);

    // Case 1: DOMException AbortError (typical browser cancel)
    {
        const c = new AbortController();
        setTimeout(() => c.abort(new DOMException('User cancelled', 'AbortError')), 30);
        try { await protocol.request({ method: 'ping' }, { signal: c.signal, timeout: 60_000 }); }
        catch (e) { if (e instanceof SdkError) console.log(`CASE 1 (DOMException AbortError): code=${e.code} msg="${e.message}"`); }
    }
    // Case 2: bare abort() with no reason
    {
        const c = new AbortController();
        setTimeout(() => c.abort(), 30);
        try { await protocol.request({ method: 'ping' }, { signal: c.signal, timeout: 60_000 }); }
        catch (e) { if (e instanceof SdkError) console.log(`CASE 2 (bare abort):                code=${e.code} msg="${e.message}"`); }
    }
    // Case 3: real timeout (control)
    {
        try { await protocol.request({ method: 'ping' }, { timeout: 50 }); }
        catch (e) { if (e instanceof SdkError) console.log(`CASE 3 (real timeout):              code=${e.code} msg="${e.message}"`); }
    }

    await protocol.close();
}
main().then(() => process.exit(0), e => { console.error(e); process.exit(1); });

before the fix:

CASE 1 (DOMException AbortError): code=REQUEST_TIMEOUT msg="AbortError: User cancelled"
CASE 2 (bare abort):                code=REQUEST_TIMEOUT msg="AbortError: This operation was aborted"
CASE 3 (real timeout):              code=REQUEST_TIMEOUT msg="Request timed out"

all three paths surface REQUEST_TIMEOUT. case 3 is correct; cases 1 and 2 are the bug.

suggested fix

add RequestAborted to SdkErrorCode and swap the four wrap sites from RequestTimeout to RequestAborted. the timeout path stays untouched — it already constructs SdkError(RequestTimeout, 'Request timed out') explicitly and passes it through cancel() as an SdkError (no wrap runs), so cases 1/2 above become REQUEST_ABORTED while case 3 stays REQUEST_TIMEOUT.

// packages/core-internal/src/errors/sdkErrors.ts
     RequestTimeout = 'REQUEST_TIMEOUT',
+    /** Request was cancelled via `AbortSignal`. Distinct from RequestTimeout. */
+    RequestAborted = 'REQUEST_ABORTED',
     ConnectionClosed = 'CONNECTION_CLOSED',

// packages/core-internal/src/shared/protocol.ts — cancel() fallback
-    const error = reason instanceof SdkError ? reason : new SdkError(SdkErrorCode.RequestTimeout, String(reason));
+    const error = reason instanceof SdkError ? reason : new SdkError(SdkErrorCode.RequestAborted, String(reason));

// packages/core-internal/src/shared/protocol.ts — pre-aborted signal check
// packages/client/src/client/client.ts — _serveFromCache pre-abort, listen() pre-abort
// each site: same swap — RequestTimeout → RequestAborted in the non-SdkError branch

test to verify: Protocol.request({ method: 'ping' }, { signal, timeout: 60_000 }) when signal aborts with a DOMException('AbortError') (or a bare abort()) rejects with SdkError.code === RequestAborted, while a timeout: 30 expiry still rejects with RequestTimeout. also flip the two pre-existing pins (abortReasonPassthrough.test.ts:53-66 and responseCache.test.ts warm-hit pre-abort) that currently assert RequestTimeout for non-SdkError abort reasons.

scope note: seven files (three source, four test — including two mandatory ABI-pin updates for the enum-membership pin and the two behavior pins that lock the wrap-as-RequestTimeout contract). all four wrap sites need to move together; leaving the cache/listen sites emitting RequestTimeout while the wire path emits RequestAborted would surface the abort as two different codes depending on whether the cache was warm. v1.x uses McpError/ErrorCode.RequestTimeout at src/shared/protocol.ts:1185 — same pattern, the backport needs the equivalent enum addition and the four-site swap.

[xudongWu2022]

Opened #2617 for this.

@sakthiveltofficial got here first with #2177 — the diagnosis and the enum + cancel() fix are theirs. That PR predates the core-internal package split so it now conflicts with main, and it covers one of the four wrap sites the triage comment above flags. Since it had been idle a while I rebased the same idea onto current main and completed it rather than leave the fix half-applied:

• all four wrap sites moved together (request() in-flight abort, request() pre-abort check, Client._serveFromCache() warm-hit pre-abort, Client.listen() pre-abort) — otherwise the same abort reports a different code depending on whether the cache was warm
• the three pins that lock the old contract: the SdkErrorCode enum-membership ABI pin, plus the behavior pins in abortReasonPassthrough.test.ts, responseCache.test.ts and listen.test.ts
• new coverage for in-flight DOMException('AbortError') and bare abort(), and a timeout: 0 control asserting the timeout path still reports RequestTimeout
• migration-guide entries and a changeset

@sakthiveltofficial — no ownership claim intended, happy to close mine if you'd rather bring #2177 up to date.

Two things left open in the PR description: the v1.x backport (would rather send separately against that branch), and whether inputRequiredDriver.ts:163/:172 should move too — they use the identical wrap but sit outside the four-site scope, so I left them out pending a maintainer call.