[BUG] MAX_THINKING_TOKENS forces every request to be a thinking request

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/4887

If your issue is a duplicate, please close it and 👍 the existing issue instead.

_{This issue will be automatically closed as a duplicate in 3 days if there are no additional comments. To prevent auto-closure, please 👎 this comment.}

🤖 Generated with Claude Code

A reason to use this environment variable is that otherwise Claude code will use more than “max tokens” for thinking. In our environment we’re limited to 32k max tokens, so it would be ideal if Claude code automatically kept thinking to a safe level based on the overall limit.

if MAX_THINKING_TOKENS is set, it would only make sense to have thinking enabled.
That being said, having a switch to enable/disable thinking would be great.

if MAX_THINKING_TOKENS is set, it would only make sense to have thinking enabled. That being said, having a switch to enable/disable thinking would be great.

No this flag is useful to limit the maximum thinking budget of the model but that does not mean we want thinking enabled on every request. Furthermore a Boolean thinking toggle also does not really address the issue, as that would be a blanket disable. The ideal functionalality imo is for Claude code to use its normal thinking logic (i.e based on keywords/context length/task complexity) while also respecting this max budget.

I agree that just because we want to set a MAX_THINKING_TOKENS as a setting, it doesn't mean, we want thinking enabled all the time.
Probably the logic assumed by the team was that, if you are setting MAX_THINKING_TOKENS it probably means you want to be using thinking mode, so a switch setting would make sense, rather than rely solely on dynamic thinking with keywords or make it default.

My observations so far on using this env variable
Is that Claude will only use as many tokens as it needs. I haven’t as of yet seen a huge increase of token usage or overthinking on simple tasks. In fact I’ve seen the opposite, because it’s always in thinking mode it’s being a lot more cautious with its changes. I’m seeing less messy mistakes than previous iterations (and my workflow has remained the same). Time will tell and so will my testing and deployment !

Thanks for the detailed bug report! We've identified the root cause and understand the confusion here. What's happening: When MAX_THINKING_TOKENS is set, it currently enables thinking mode for all requests and sets the budget to that value. We agree this is confusing - the name suggests it should only limit the maximum, not force thinking on every request. Modifying this behavior now would be a backwards-incompatible change that could break existing workflows for users who rely on the current behavior.

For now, we recommend only setting MAX_THINKING_TOKENS when you want thinking enabled on all requests. If you need conditional thinking (only on complex requests), leave this unset and let Claude Code use its normal heuristics based on trigger words like 'think', 'think harder', or 'ultrathink' in your prompts.

@bogini Would you happen to be able to clarify if there's a "level" of thinking that's enabled here? As in, Claude Code uses "think" level thinking or "ultrathink" level thinking with this variable set? Just wondering what I should expect in terms of performance when it's enabled.

@christabone When MAX_THINKING_TOKENS is set, it forces thinking mode on all requests with the budget you specified as the cap. It doesn't set a specific "level" like "think" (4k tokens) or "ultrathink" (32k tokens) - instead, every request gets thinking enabled and the model uses what it needs up to your limit.

All requests will be slower because thinking is forced on, even for simple queries like "hello". The model tries to be efficient and won't always use the full budget, but there's overhead from going through the thinking pipeline on every single request.

So with MAX_THINKING_TOKENS=20000, you're essentially forcing thinking on everything with a 20k cap, rather than selectively enabling it. This is why the current behavior is confusing - the name makes it seem to be a cap for when thinking is triggered naturally, not a force-enable flag.

@bogini Thank you very much for the reply and info, that's great to know!

@bogini thanks for the explanation.

I agree it would break the workflow, as i am using it to enable thinking instead of having to write the keywords every prompt.

But I have a question. What is the min/max limit we can setup for MAX_THINKING_TOKENS or what is recommended?

Is it the same as think/ultrathink 4k / 32k?

Would it use more than 32k if we were to set it to let's say 64k? How high can we go with the 1M model?

Thanks

The current system of prompting to enable thinking is ambiguous and confusing. Is my request a think request? A think hard? A mega super duper think? Are these programmatically defined or does the model have a say - how much, when, and why?

The fast adoption of GPT-5-Codex shows the appetite for a generalized model that is _very good_ at prompting and knowing when a given task requires a lot of thought, or a little. I hope that this approach will be emulated by future models and agents in Claude.

For reference, in August this was the error we were receiving before we set the environment variable:

  ⎿ API Error: 400 {"type":"application_error","detail":"API Error: The model returned the following errors: `max_tokens` must be greater
     than `thinking.budget_tokens`. Please consult our documentation at 
    https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#max-tokens-and-context-window-size","status_code":400}

Setting CLAUDE_CODE_MAX_OUTPUT_TOKENS didn't fix it.

This might be due to the quirky way we integrate with Anthropic's API's, so we'll give it a try again without MAX_THINKING_TOKENS enabled.

The Claude documentation on this could benefit from correction and clarification. Currently, it reads:

MAX_THINKING_TOKENS: Force a thinking for the model budget

https://docs.claude.com/en/docs/claude-code/settings#environment-variables

Maybe this instead?

MAX_THINKING_TOKENS: Forces thinking mode on all requests and sets the maximum number of tokens the model can use for thinking.

Thanks for the detailed bug report! We've identified the root cause and understand the confusion here. What's happening: When MAX_THINKING_TOKENS is set, it currently enables thinking mode for all requests and sets the budget to that value. We agree this is confusing - the name suggests it should only limit the maximum, not force thinking on every request. Modifying this behavior now would be a backwards-incompatible change that could break existing workflows for users who rely on the current behavior.

This is very poor reasoning to not fix a bug. Aligning an incorrect implementation with the documented, expected behaviour should not be avoided just because some people may rely on it. XKCD 1172 (https://xkcd.com/1172/) comes to mind.

Thanks for the detailed bug report! We've identified the root cause and understand the confusion here. What's happening: When MAX_THINKING_TOKENS is set, it currently enables thinking mode for all requests and sets the budget to that value. We agree this is confusing - the name suggests it should only limit the maximum, not force thinking on every request. Modifying this behavior now would be a backwards-incompatible change that could break existing workflows for users who rely on the current behavior. For now, we recommend only setting MAX_THINKING_TOKENS when you want thinking enabled on all requests. If you need conditional thinking (only on complex requests), leave this unset and let Claude Code use its normal heuristics based on trigger words like 'think', 'think harder', or 'ultrathink' in your prompts.

@bogini since cloud providers like AWS Bedrock are subject to relatively harsh limits both AWS and Anthropic recommend to set MAX_THINKING_TOKENS to 1024. This means that people relying on cloud providers are basically forced to enable reasoning capabilities all the time. Moreover, the UI doesn't indicate this at all and still lets you toggle reasoning off / on. Please reconsider changing this functionality or adding other environment variables for a more granular control. In my opinion backwards incompatibility is not a good reason to leave it unchanged.

https://builder.aws.com/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide
https://docs.claude.com/en/docs/claude-code/amazon-bedrock#5-output-token-configuration

Why can't claude code understand what the cloud's max thinking budget is and adhere to that? FTW, we use Bedrock and before MAX_THINKING_TOKENS was required to be set or Claude Code would go nuts with thinking and overflow it's output limit. Now it doesn't do that (as far as I've seen).

Yeah, this is hitting us as well. Under one cloud provider, we used to say

"Think about {prompt}" and it would work.

That provider had a bad day, we're using a new one, and now when we "Think about {prompt}" we get the error from here.

We semi-regularly have to switch cloud providers, as latency concerns or others pick up, and our users get confused when the Claude Code UI shows any new text (like "thinking") under different circumstances

edit to add: a smaller request that would meet my needs: if you give me the ability to customize/postfix an error message, I can translate these errors into how my users should solve them or reason about them.

Just hit that

  ⎿  API Error: 400 {"type":"application_error","detail":"API Error: The model returned the following errors: `max_tokens` must be greater than `thinking.budget_tokens`. Please 
     consult our documentation at https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#max-tokens-and-context-window-size","status_code":400}

Just hit that `` ⎿  API Error: 400 {"type":"application_error","detail":"API Error: The model returned the following errors: max_tokens must be greater than thinking.budget_tokens. Please consult our documentation at https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#max-tokens-and-context-window-size","status_code":400} ``

That seems normal. you cannot set max_tokens lower than thinking tokens, as it doesn't make sense.
if you enable thinking, then max_tokens usually includes all tokens, normal or thinking, hence you see where its going.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

still issue with haiku

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.