Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(errors): a context overflow leads with `prompt is too long` (item 8)
Jack Rudenkoe0b401699b11
diff --git a/packages/cli/src/handlers/composed-handler-error.test.ts b/packages/cli/src/handlers/composed-handler-error.test.tsindex fa811a9d..e2f57bdc 100644--- a/packages/cli/src/handlers/composed-handler-error.test.ts+++ b/packages/cli/src/handlers/composed-handler-error.test.ts@@ -99,6 +99,7 @@ interface CapturedErrorBody {error?: {type?: string;message?: string;+ upstream_status?: number;};}@@ -157,6 +158,64 @@ describe("ComposedHandler.handle — error surfacing wiring", () => {expect(captured.body?.error?.message).toContain("exceeded your current quota");});+ test("a context overflow reaches the client LEADING with `prompt is too long`", async () => {+ // The whole point of item 8: providers state the overflow in their own+ // words, and no Anthropic client matches those words. Without the phrase the+ // client classifies this as a generic invalid request and never offers to+ // compact. Asserted through the handler, not the builder, because the+ // builder being right proves nothing if the wiring never asks for it.+ stubUpstream(400, {+ error: {+ message:+ "This model's maximum context length is 128000 tokens. However, your messages resulted in 200000 tokens.",+ type: "invalid_request_error",+ code: "context_length_exceeded",+ },+ });+ const { c, captured } = makeContext();+ await makeHandler().handle(c, PAYLOAD);++ expect(captured.status).toBe(400);+ expect(captured.body?.error?.type).toBe("invalid_request_error");+ expect(captured.body?.error?.message?.startsWith("prompt is too long")).toBe(true);+ // The 400-remap contract: the real upstream status still rides along, and+ // the provider's own sentence is still there for a human to read.+ expect(captured.body?.error?.upstream_status).toBe(400);+ expect(captured.body?.error?.message).toContain("maximum context length is 128000 tokens");+ });++ test("a 413 overflow is remapped to 400 and keeps its upstream status", async () => {+ stubUpstream(413, {+ error: { message: "Payload too large: the prompt exceeds this model's context window" },+ });+ const { c, captured } = makeContext();+ await makeHandler().handle(c, PAYLOAD);++ expect(captured.status).toBe(400);+ expect(captured.body?.error?.message?.startsWith("prompt is too long")).toBe(true);+ expect(captured.body?.error?.upstream_status).toBe(413);+ });++ test("a parameter rejection is NOT relabelled as an oversized prompt", async () => {+ // The ordering guard, end to end. `max_output_tokens` contains the word+ // "tokens"; adapters.md records the incident where that alone was enough to+ // report a 6.7 KB prompt against a 1.05M window as too large.+ stubUpstream(400, {+ error: {+ message: "Unknown parameter: 'max_output_tokens'.",+ type: "invalid_request_error",+ param: "max_output_tokens",+ code: "unknown_parameter",+ },+ });+ const { c, captured } = makeContext();+ await makeHandler().handle(c, PAYLOAD);++ expect(captured.body?.error?.message ?? "").not.toContain("prompt is too long");+ // Unchanged from before item 8: not terminal, so the status passes through.+ expect(captured.status).toBe(400);+ });+test("terminal auth 401 is surfaced as 400 (not silently retried)", async () => {stubUpstream(401, { error: { message: "invalid api key" } });const { c, captured } = makeContext();diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.tsindex 83df2909..640a47c1 100644--- a/packages/cli/src/handlers/composed-handler.ts+++ b/packages/cli/src/handlers/composed-handler.ts@@ -60,7 +60,11 @@ import { sniffDevinStreamHead } from "./shared/devin-stream-head-sniffer.js";import { hasActionableLink, hasModelUnsupportedWording } from "./shared/model-unsupported.js";import { filterIdentity } from "./shared/openai-compat.js";import { hasPlanLimitWording, isQuotaExhaustionError } from "./shared/quota-exhaustion.js";-import { isRequestShapeError } from "./shared/request-shape.js";+import {+ CONTEXT_OVERFLOW_PHRASE,+ isContextOverflowError,+ isRequestShapeError,+} from "./shared/request-shape.js";import { sniffResponsesStreamHead } from "./shared/stream-head-sniffer.js";import { createAnthropicPassthroughStream } from "./shared/stream-parsers/anthropic-sse.js";import { createDevinConnectStream } from "./shared/stream-parsers/devin-connect.js";@@ -968,6 +972,12 @@ export class ComposedHandler implements ModelHandler {status: response.status,hint,providerMessage: providerMsg,+ // The one phrase an Anthropic client recognises for an oversized+ // prompt. Providers state the same fact in their own words, which+ // no client matches — see CONTEXT_OVERFLOW_PHRASE.+ leadPhrase: isContextOverflowError(response.status, errorText)+ ? CONTEXT_OVERFLOW_PHRASE+ : undefined,});// Carry the ORIGINAL upstream status as a structured field so// machine consumers (probe classification) can tell a remapped@@ -1783,6 +1793,13 @@ export function getRecoveryHint(}return "Request format may be incompatible with provider.";}+ // 413 is "Payload Too Large" by definition, and until now fell through to+ // "Unexpected HTTP 413 from <provider>" — a status name where the actionable+ // advice already exists three lines above. Gated on the narrow predicate, so a+ // 413 about something other than the prompt keeps the generic line.+ if (isContextOverflowError(status, errorText)) {+ return "Input too large. Reduce message history or use a larger-context model.";+ }if (status >= 500) {return "Server error — retry after a brief wait.";}diff --git a/packages/cli/src/handlers/shared/anthropic-error.ts b/packages/cli/src/handlers/shared/anthropic-error.tsindex 90d1f68f..c7d1e7e9 100644--- a/packages/cli/src/handlers/shared/anthropic-error.ts+++ b/packages/cli/src/handlers/shared/anthropic-error.ts@@ -3,6 +3,8 @@* All proxy error responses MUST use this format.*/+import { isContextOverflowError } from "./request-shape.js";+export type AnthropicErrorType =| "invalid_request_error"| "authentication_error"@@ -217,6 +219,16 @@ export function isTerminalError(status: number, bodyText: string, terminal429: bif (status === 426) return true;// Billing/quota exhaustion surfaced as a 429 (provider-specific signals).if (status === 429 && terminal429) return true;+ // A prompt larger than the model's context window is terminal BY ARITHMETIC:+ // re-sending the identical request can only produce the identical rejection.+ // Terminal here means the envelope is remapped to 400 and carries the rich+ // surfaced message, which is the only path on which the client ever sees the+ // `prompt is too long` phrase it pattern-matches — the plain pass-through+ // forwards the provider's own wording, which no client recognises.+ //+ // It does NOT change the fallback chain: `fallback-handler` only widens on a+ // recovered upstream 401/402/403/429, and an overflow is none of those.+ if (isContextOverflowError(status, bodyText)) return true;const lower = (bodyText || "").toLowerCase();@@ -272,11 +284,25 @@ export function buildSurfacedErrorMessage(opts: {status: number;hint: string;providerMessage: string;+ /**+ * A phrase the CLIENT pattern-matches, placed at the very front of the line.+ *+ * It LEADS for two independent reasons, and either alone would be enough.+ * `sanitizeErrorMessage` caps the message at 600 characters, so a phrase+ * appended after provider prose can be cut off — and a client matching a+ * truncated phrase misses silently. And Claude Code's own message classifier+ * tests `startsWith("prompt is too long")`, not a substring, so the position+ * is itself load-bearing.+ *+ * Only `CONTEXT_OVERFLOW_PHRASE` uses this today. See `request-shape.ts`.+ */+ leadPhrase?: string;}): string {- const { providerDisplayName, status, hint, providerMessage } = opts;+ const { providerDisplayName, status, hint, providerMessage, leadPhrase } = opts;const head = `${providerDisplayName} error (HTTP ${status})`;const parts: string[] = [head];if (hint) parts[0] = `${head}: ${hint}`;+ if (leadPhrase && !parts[0].startsWith(leadPhrase)) parts[0] = `${leadPhrase} — ${parts[0]}`;const detail = (providerMessage || "").trim();if (detail && !parts[0].includes(detail)) {// Keep the surfaced line bounded — providers occasionally echo huge bodies.diff --git a/packages/cli/src/handlers/shared/request-shape.test.ts b/packages/cli/src/handlers/shared/request-shape.test.tsindex ce9e036f..71f2c9c7 100644--- a/packages/cli/src/handlers/shared/request-shape.test.ts+++ b/packages/cli/src/handlers/shared/request-shape.test.ts@@ -1,6 +1,16 @@import { describe, expect, test } from "bun:test";import { getRecoveryHint } from "../composed-handler.js";-import { isRequestShapeError } from "./request-shape.js";+import {+ buildSurfacedErrorMessage,+ extractUpstreamStatus,+ isTerminalError,+ wrapAnthropicError,+} from "./anthropic-error.js";+import {+ CONTEXT_OVERFLOW_PHRASE,+ isContextOverflowError,+ isRequestShapeError,+} from "./request-shape.js";const unknownParameter = `{"error":{"message":"Unknown parameter: 'max_output_tokens'.","type":"invalid_request_error","param":"max_output_tokens","code":"unknown_parameter"}}`;const unsupportedParameter = `{"error":{"message":"Unsupported parameter: 'messages'. In the Responses API, this parameter has moved to 'input'.","type":"invalid_request_error","param":"messages","code":"unsupported_parameter"}}`;@@ -39,3 +49,132 @@ describe("request-shape classification and recovery hints", () => {);});});++/**+ * Item 8 — a context overflow must reach the client wearing the phrase the+ * client matches.+ *+ * The provider bodies below reuse the shapes the sibling tests above already+ * use, plus the structured codes named in `adapters.md`'s "read the code, not+ * the prose" rule. None of them is a captured live 4xx: they are written from+ * documented relay shapes, and are labelled as such here for the same reason the+ * `stop`/`top_p` rejection wordings in this batch are.+ */+const requestTooLarge = `{"error":{"message":"Request too large for gpt-5.4 in organization org-x on tokens per min (TPM): Limit 30000, Requested 40000.","type":"tokens","code":"request_too_large"}}`;+const anthropicOverflow = `{"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 215000 tokens exceed the 200000 maximum"}}`;+const payloadTooLarge = `{"error":{"message":"Payload too large: the prompt exceeds the context window of this model"}}`;+const maxTokensComplaint = `{"error":{"message":"max_tokens: the answer must be at most 8192 tokens","type":"invalid_request_error","code":"invalid_request_error"}}`;+const unrelated400 = `{"error":{"message":"bad request"}}`;+const bigFile413 = `{"error":{"message":"uploaded file is too big"}}`;++describe("context-overflow classification (item 8)", () => {+ test("H: the provider's structured code is read first", () => {+ expect(isContextOverflowError(400, contextOverflow)).toBe(true);+ expect(isContextOverflowError(400, requestTooLarge)).toBe(true);+ });++ test("I: prose is matched when a gateway dropped the code", () => {+ const proseOnly = `{"error":{"message":"This model's maximum context length is 128000 tokens."}}`;+ expect(isContextOverflowError(400, proseOnly)).toBe(true);+ expect(isContextOverflowError(400, anthropicOverflow)).toBe(true);+ });++ test("J: a PARAMETER rejection is never an overflow, whatever words it uses", () => {+ // The ordering guard. `max_output_tokens` contains "tokens"; inverting this+ // re-opens the bug adapters.md records, where a parameter rejection was+ // rendered as advice to shorten a prompt that was never too long.+ expect(isContextOverflowError(400, unknownParameter)).toBe(false);+ expect(isContextOverflowError(400, unsupportedParameter)).toBe(false);+ // This is where the guard is actually load-bearing rather than+ // belt-and-braces: at 400 none of the phrase arms can match a parameter+ // rejection anyway, but the 413 arm only asks the body to mention "token",+ // and `max_output_tokens` does. Deleting the guard flips this line alone.+ expect(isContextOverflowError(413, unknownParameter)).toBe(false);+ });++ test("K: an output-length complaint is not an input overflow", () => {+ expect(isContextOverflowError(400, maxTokensComplaint)).toBe(false);+ });++ test("L: an empty or unrelated body is not an overflow", () => {+ expect(isContextOverflowError(400, "")).toBe(false);+ expect(isContextOverflowError(400, unrelated400)).toBe(false);+ expect(isContextOverflowError(500, `{"error":{"message":"internal"}}`)).toBe(false);+ });++ test("M: a 413 naming the prompt is an overflow; a 413 naming something else is not", () => {+ expect(isContextOverflowError(413, payloadTooLarge)).toBe(true);+ expect(isContextOverflowError(413, bigFile413)).toBe(false);+ });++ test("N: a 413 overflow now gets the size hint instead of 'Unexpected HTTP 413'", () => {+ expect(getRecoveryHint(413, payloadTooLarge, "OpenAI")).toContain("Input too large");+ expect(getRecoveryHint(413, bigFile413, "OpenAI")).toBe("Unexpected HTTP 413 from OpenAI.");+ });+});++describe("the surfaced overflow message (item 8)", () => {+ test("O: an overflow is terminal, so it takes the 400-remap path", () => {+ expect(isTerminalError(400, contextOverflow, false)).toBe(true);+ expect(isTerminalError(413, payloadTooLarge, false)).toBe(true);+ // Unchanged: an ordinary 400 is still not terminal.+ expect(isTerminalError(400, unrelated400, false)).toBe(false);+ // Unchanged: a parameter rejection is still not terminal.+ expect(isTerminalError(400, unknownParameter, false)).toBe(false);+ });++ test("P: the phrase LEADS the surfaced line", () => {+ const message = buildSurfacedErrorMessage({+ providerDisplayName: "OpenAI",+ status: 400,+ hint: getRecoveryHint(400, contextOverflow, "OpenAI"),+ providerMessage: "This model's maximum context length is 128000 tokens.",+ leadPhrase: CONTEXT_OVERFLOW_PHRASE,+ });+ // startsWith, not includes: sanitizeErrorMessage caps the line at 600 chars,+ // and the client's own message classifier tests the prefix.+ expect(message.startsWith(CONTEXT_OVERFLOW_PHRASE)).toBe(true);+ expect(message).toContain("OpenAI error (HTTP 400)");+ expect(message).toContain("Input too large");+ });++ test("Q: the phrase survives sanitization at the 600-char cap", () => {+ const envelope = wrapAnthropicError(+ 400,+ buildSurfacedErrorMessage({+ providerDisplayName: "OpenAI",+ status: 400,+ hint: getRecoveryHint(400, contextOverflow, "OpenAI"),+ providerMessage: "x".repeat(5000),+ leadPhrase: CONTEXT_OVERFLOW_PHRASE,+ }),+ "invalid_request_error",+ 400+ );+ expect(envelope.error.message.startsWith(CONTEXT_OVERFLOW_PHRASE)).toBe(true);+ expect(envelope.error.message.length).toBeLessThanOrEqual(600);+ });++ test("R: the 400-remap contract is intact — upstream_status is recoverable", () => {+ const envelope = wrapAnthropicError(+ 400,+ `${CONTEXT_OVERFLOW_PHRASE} — OpenAI error (HTTP 413)`,+ "invalid_request_error",+ 413+ );+ expect(envelope.error.upstream_status).toBe(413);+ expect(extractUpstreamStatus(JSON.stringify(envelope))).toBe(413);+ });++ test("S: a non-overflow terminal error is unchanged — no phrase is added", () => {+ const message = buildSurfacedErrorMessage({+ providerDisplayName: "Sakana Fugu",+ status: 401,+ hint: "Check API key / OAuth credentials.",+ providerMessage: "invalid api key",+ });+ expect(message).toBe(+ "Sakana Fugu error (HTTP 401): Check API key / OAuth credentials. — invalid api key"+ );+ });+});diff --git a/packages/cli/src/handlers/shared/request-shape.ts b/packages/cli/src/handlers/shared/request-shape.tsindex f45c7755..b384cf1e 100644--- a/packages/cli/src/handlers/shared/request-shape.ts+++ b/packages/cli/src/handlers/shared/request-shape.ts@@ -35,3 +35,77 @@ export function isRequestShapeError(errorBody: string): boolean {lower.includes("invalid parameter:"));}++/**+ * The literal phrase an Anthropic client pattern-matches to recognise a context+ * overflow.+ *+ * Not decorative and not paraphrasable. Claude Code tests error text for this+ * exact string (verified in the 2.1.273 binary:+ * `n.includes("prompt is too long") || n.includes("input is too long for requested model")`),+ * uses it to classify the turn as `prompt_too_long` rather than a generic+ * invalid request, and parses `prompt is too long[^0-9]*(\d+) tokens? > (\d+)`+ * out of it for the actual/limit numbers it shows the user. A provider that says+ * "This model's maximum context length is 128000 tokens" says the same thing in+ * words no client matches, so the fact is lost in translation unless claudish+ * restates it.+ */+export const CONTEXT_OVERFLOW_PHRASE = "prompt is too long";++/**+ * Did this error say the INPUT was too big for the model's context window?+ *+ * Sibling of `isRequestShapeError`, and deliberately ordered behind it: the two+ * questions are mutually exclusive attributions of the same 400, and a+ * parameter rejection frequently names a parameter with "token" in it. Reading+ * this one first re-opens the `max_output_tokens` bug `adapters.md` records, so+ * the guard is built into the predicate rather than left to each caller to+ * remember.+ *+ * Structured `code` FIRST, prose second — the rule `adapters.md` states as the+ * general lesson of three separate incidents: when the provider ships a+ * structured code, reading it beats inferring from its prose. The prose arm+ * exists only because gateways in front of a vendor routinely forward the+ * message and drop the code.+ *+ * Narrow on purpose. It must not match a rejection that merely MENTIONS length+ * (a `max_tokens` complaint, an oversized image), because every match rewrites+ * the surfaced message into a claim about the prompt.+ */+export function isContextOverflowError(status: number, errorBody: string): boolean {+ if (!errorBody) return false;+ // A parameter rejection is never a size problem, whatever words it uses.+ if (isRequestShapeError(errorBody)) return false;++ const lower = errorBody.toLowerCase();++ // 1. The provider's own structured attribution.+ if (+ lower.includes("context_length_exceeded") ||+ lower.includes("string_above_max_length") ||+ lower.includes("request_too_large") ||+ lower.includes("context_window_exceeded") ||+ lower.includes("prompt_too_long")+ ) {+ return true;+ }++ // 2. Prose, for gateways that drop the code. Each phrase names the INPUT and a+ // LIMIT together; none of them can be produced by an output-length or+ // parameter complaint.+ if (+ lower.includes("maximum context length is") ||+ lower.includes("reduce the length of the messages") ||+ lower.includes("input is too long") ||+ lower.includes(CONTEXT_OVERFLOW_PHRASE)+ ) {+ return true;+ }++ // 3. HTTP 413 is "Payload Too Large" by definition. Gated on the body naming+ // the input at all, so a 413 about an uploaded file is not relabelled as a+ // prompt problem.+ if (status === 413 && (lower.includes("token") || lower.includes("context"))) return true;++ return false;+}