Skip to content

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.ts
index 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.ts
index 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.ts
index 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: b
if (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.ts
index 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.ts
index 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;
+}