Skip to content
FeaturesError referenceBlogDocsChangelog

API Error: Claude's response exceeded the 32000 output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable

Your request was accepted, your context was fine, and the model started writing. It then produced more text in one response than the per-response ceiling allows. This is not the context window, not a quota, not a rate limit and not a truncated stream — it is a cap on the size of a single answer, and the message hands you the exact variable that sets it.

Data as of 2026-09. Vendor limits and defaults change; check the official docs for current values before acting on any number below.

Input budget and output budget are not the same budget

The reflex on seeing a token limit in an AI coding tool is to run /compact. Compaction does nothing for this error. Compaction shrinks the input side — the conversation you have accumulated. This ceiling governs how much the model is allowed to write in one turn, and it is unchanged by how short your conversation is. People lose ten minutes clearing context, ask for the same large file again, and land on the identical message.

The number in your message is the limit in force in your session, which is why the error names CLAUDE_CODE_MAX_OUTPUT_TOKENS rather than telling you to contact anyone. Raising it is a one-line environment change. Whether raising it is the right move is the actual question, and it depends on why the response got that big.

Is retrying useful?

No. The same request asks for the same work, and the same work is the same length.

This failure is a property of the task, not the connection. Ask a model to emit a 4,000-line file and it will exceed the ceiling on every attempt; the variance between runs is nowhere near large enough to sneak under a limit you blew past.

There is a cost to trying anyway that is easy to overlook. Output tokens count against your output-token rate limit as they are actually produced, so an attempt that runs into the ceiling has already spent them. Three identical retries spend three times the output-token budget and deliver nothing usable. The retry that makes sense is the one that comes after you have raised the ceiling or changed the shape of the request.

How high the ceiling can go

Setting CLAUDE_CODE_MAX_OUTPUT_TOKENS above the model’s own maximum output buys nothing, because the model’s limit is the binding one. On the synchronous Messages API, Claude Opus 5, Claude Sonnet 5 and Claude Fable 5.1 document a maximum output of 128K tokens, and Claude Haiku 4.5 documents 64K tokens. Whatever you set, you are operating under that.

One piece of reassurance worth having, because it stops a common hesitation: max_tokens does not factor into the output-token rate limit. Only tokens actually produced count. Raising the ceiling therefore carries no rate-limit penalty by itself — a generous cap that is rarely reached costs you nothing. The Anthropic docs do describe a larger output tier, up to 300k tokens, but it is a Message Batches API beta behind the output-300k-2026-03-24 header, not something an interactive coding session reaches for.

Which of the two problems you have

Both cases print the same message. They are told apart by predictability, not by the error text.

  • You can name the prompt that triggers it. “Write the whole migration”, “output the complete file”, “generate the full report” — if the same kind of request fails every time and ordinary work never does, the response genuinely needs to be that large. This is the structural case.
  • It fired once, on something only slightly bigger than usual. Work of this size normally completes, and this one landed just over the line. This is the ceiling case.
  • It started after you switched models. Model families document different maximum outputs, and a response size that was comfortable on one can be over the line on another. Check what you switched to before you change anything else.
  • It fires in a scripted or headless run but not interactively. Environment variables are per-process: a shell that exports the variable for your interactive session is not the shell your CI job runs in. Print the variable in the failing environment rather than assuming it inherited.

Fixes, one per case

  • Ceiling case — export CLAUDE_CODE_MAX_OUTPUT_TOKENS to a value at or below your model’s documented maximum output, in the environment that actually launches claude, then restart the session. This is the whole fix; do not also restructure the task.
  • Structural case — raising the limit only moves the wall. Ask for the work in pieces: have the model write files through its editing tools across several tool calls rather than printing one enormous block, or split the request by module, by section, by file. A turn that writes three files in three tool calls has three separate output budgets; a turn that prints all three has one.
  • Model-switch case — either move back to a model with a larger documented maximum output, or accept the smaller one and split the work. If you switch with /model, budget for the side effect: each model has its own prompt cache, so the first request after the switch re-reads the entire conversation uncached.
  • Environment case — set the variable where the process is actually launched — the CI job definition, the service unit, the wrapper script — and verify it from inside that environment.

Confirming it is fixed, not merely postponed

Re-run the request that failed and check that the output ends, rather than checking that it got further. A longer response that still stops mid-sentence is the same failure at a higher ceiling, and it is easy to accept by accident because it looks like progress. Open the artifact and look for a real ending: the closing brace, the final section, the last test case.

Then run the largest request of that shape twice. Response lengths vary between runs, so a single success just below a ceiling is not evidence that you have headroom — it is evidence that you got close. For the structural fix, confirm that no single turn is still trying to emit the whole artifact; if one is, you split the request in the description and not in the execution.