"Claude's response exceeded the 32000 output token maximum": what to do when the env var doesn't help

You asked for a large refactor. The agent generated for several minutes, the terminal kept filling up, and the response stopped with this line:

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

The number looks like a model limit. Most of the time it is not. 32000 is the cap the CLI placed on that request, and it is usually well below what the model can deliver. While you look for the "right limit" to raise, the cost of the attempt keeps running.

What does "exceeded the 32000 output token maximum" mean?

It means the model stopped because the response hit the request's output token cap. The technical reason is stop_reason: max_tokens. It is not a permission problem, not a network drop and not a locked account. The call reached the model, the model answered, and the server cut the response at the agreed cap.

The number in the message is the effective cap for that call. It can be 32000, it can be 64000. That is why two people on the same Claude Code version see different numbers in the same sentence.

Why 32000 if the model supports 128K?

Because Claude Code asks for less than the model delivers by default. The official documentation is explicit: for a model ID Claude Code cannot resolve to a model it knows, the default is 32000 and the cap is 128000. Known models have their own defaults and caps, which vary by model.

Anthropic's model table, checked on 14 November 2026, shows the maximum output on the model side:

Model	Context window	Max output
Claude Opus 5.5, Sonnet 5.5, Haiku 5.5	1M tokens	128K tokens
Claude Opus 4.6, Sonnet 4.6	1M tokens	128K tokens
Claude Opus 4.5, Sonnet 4.5, Haiku 4.5	200K tokens	64K tokens

In other words: the model accepts 128 thousand output tokens while the request may be asking for 32 thousand. The gap between the two is what produces the error.

The most common cause of 32000 is an "unrecognized" model. That happens with a custom ID, an alias created at the gateway, a deployment with a different name, or your own base URL. The model may be perfectly known to you. If the CLI cannot map that ID to a model it knows, it uses the default.

How do you raise the cap with CLAUDE_CODE_MAX_OUTPUT_TOKENS?

Export the variable before opening the session:

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
claude

To apply it in every terminal, add it to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
  }
}

Sessions that are already open do not read the change. Open a new one after exporting. And the value is not absolute: the documentation says Claude Code lowers a value above a model's cap to the cap. If the model delivers 64K, asking for 128K does not turn it into 128K.

To check what the CLI is seeing, claude doctor validates environment variables that are outside the expected range. In Verboo Code, the equivalent is verboo doctor.

Why did raising the env var change nothing?

In most reports, one of these three things happened:

What happened	How to confirm	What to do
The variable was exported in the wrong shell, or the session was already open	Run echo $CLAUDE_CODE_MAX_OUTPUT_TOKENS in the same terminal where you start Claude Code	Export it again and open a new session
The value went above the model cap	Compare the number with the max output table above	Use a value within the cap, or a model with a higher cap
The cap is not the bottleneck: the agent tries to deliver a whole file in one turn	The response gets cut again, even with the higher cap	Split the work into blocks and commit between them

There is one more symptom that confuses people. After the error, the agent keeps "thinking". The CLI tries to resume the work where it stopped, with a nudge to continue, and repeats that a few times. If the task is too large, every resume hits the same cap and burns more tokens. The session did not die. The budget did.

How do you split the task so it does not hit the cap again?

This request works as a permanent project instruction or as the first message of the task:

Do not write whole files in a single turn. Work in blocks of up to 200 lines,
run the tests after each block and commit before moving on. If the next block
would exceed that, stop and show me the plan instead of continuing.

Three habits reduce the problem without touching any limit:

1. Ask for the plan first and approve it in parts, before allowing writes.
2. One file per turn, with tests after each one.
3. Commit before asking for the next part. If it cuts, you lose nothing you already finished.

When should you switch engines instead of fighting the limit?

If the error keeps coming back because your gateway uses IDs the CLI does not recognize, raising the variable is a patch. In Verboo Code the platform models are recognized by the CLI itself, so the output limit comes from the model configuration instead of a 32 thousand default for an unknown ID. You can switch engines with /model and see the session spend with /cost.