「Thinking budget exceeds」エラーの原因と対処法(Claude Code)
「Thinking budget exceeds output limit」はMAX_THINKING_TOKENSが出力上限を超えたときに出ます。原因と環境変数での直し方をたどります。
「Thinking budget exceeds output limit」は予算が出力枠を食い尽くした状態
Claude Codeで拡張思考(extended thinking)を使っているときに、次のAPIエラーで応答が返らなくなることがあります。
API Error: 400 ... max_tokens must be greater than thinking.budget_tokens原因は単純な不等式です。thinkingの予算(thinking.budget_tokens)が、許可されている最大出力トークン数(max_tokens)以上になっています。実際の回答を書く枠が残っていません。thinkingと本文の回答は同じ出力トークン数の枠を分け合っています。予算側が枠いっぱいかそれ以上を占有すると本文を書く余地がなくなり、APIがリクエストごと拒否します。
Claude Codeが自動調整するため通常は起きない
Claude Codeは、この2つの値を自動的に調整します。MAX_THINKING_TOKENSを明示的に指定していても、Claude Code側が出力上限とのバランスを取ってリクエストを組み立てるため、通常はこのエラーに遭遇しません。
それでもこのエラーが出たときは、MAX_THINKING_TOKENSとCLAUDE_CODE_MAX_OUTPUT_TOKENSの設定値を確かめます。エラーの対処として示されているのも、出力上限を思考予算より上げることです。
MAX_THINKING_TOKENSを未設定のままなら、adaptive reasoning対応のモデルは思考の深さを自分で決めます。それ以外のモデルではキャップの値がそのまま予算になります。Opus 4.6とSonnet 4.6はCLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1で固定予算に戻せます。この経路ではMAX_THINKING_TOKENSの値が予算を決めるため、出力上限との関係を確かめる価値があります。
まず現在の設定値を確認する
対処に入る前に、自分の環境で両方の値がどう設定されているかを確認します。どちらか一方だけ設定していて、もう一方は既定値のままというケースも多いため、まず現状を正確に把握してから対処法を選ぶのが近道です。設定ファイルやCI設定など、複数の場所で環境変数を渡している場合は、実際にClaude Codeへ渡っている値と自分の意図がずれていないかも合わせて丁寧に確認してください。
echo "MAX_THINKING_TOKENS=$MAX_THINKING_TOKENS"
echo "CLAUDE_CODE_MAX_OUTPUT_TOKENS=$CLAUDE_CODE_MAX_OUTPUT_TOKENS"たとえば出力上限8,000に対しthinking予算も8,000以上にしていると、thinkingだけで出力枠を使い切ってしまいます。本文用のトークンが1つも残りません。この2つの値の関係は、プロバイダーを問わず設定値で確かめてください。
対処法1: MAX_THINKING_TOKENSを下げる
もっとも直接的な対処は、thinkingの予算そのものを出力上限より小さい値に下げることです。
export MAX_THINKING_TOKENS=4096MAX_THINKING_TOKENSはfixed thinking budget方式のモデル(Opus 4.6・Sonnet 4.6など)に対する固定思考予算です。Claude Codeは内部でこの値を「最大出力トークン数より1トークン以上小さく」「1,024トークンを下回らない」よう自動でキャップします。
対処法2: CLAUDE_CODE_MAX_OUTPUT_TOKENSを引き上げる
逆に出力上限側を引き上げる方法もあります。
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16000CLAUDE_CODE_MAX_OUTPUT_TOKENSは最大出力トークン数を設定する環境変数で、既定値と上限はモデルごとに異なります。Claude Codeが認識していないモデルID(ゲートウェイ経由の独自名など)では既定32,000トークンが使われ、モデル自身の上限を超える指定はその上限まで自動的に切り下げられます。値を上げるとauto-compaction(自動圧縮)が発動するまでの実効的な余裕が減る点には十分に注意してください。
モデル別の最大出力トークン
現行モデルの最大出力(同期のMessages API基準)は次のとおりです。値を大きく超えるMAX_THINKING_TOKENSを設定していないか、この表と照らし合わせて確認できます。
| モデル | 最大出力トークン |
|---|---|
| Claude Opus 5 | 最大出力トークン128,000 |
| Claude Sonnet 5 | 最大出力トークン128,000 |
| Claude Fable 5.1 | 最大出力トークン128,000 |
| Claude Fable 5 | 最大出力トークン128,000 |
| Claude Haiku 4.5 | 最大出力トークン64,000 |
Haiku 4.5は他の現行モデルの半分の出力上限しかありません。他モデルで問題なく動いていたMAX_THINKING_TOKENSの値を使い回すと、Haiku 4.5だけこのエラーになることがあります。モデルを切り替えるタスクでは、切り替え先の出力上限も合わせて見直すのが確実です。モデルごとの特性の違いはClaudeモデル比較でも整理しています。
似ているが原因が違うエラーと区別する
thinking関連のエラーは複数あり、症状だけでは区別しづらいことがあります。
| メッセージ | 何が起きているか | 対処 |
|---|---|---|
max_tokens must be greater than thinking.budget_tokens | 何が起きているかthinkingの予算が出力上限を超えている(本記事) | 対処MAX_THINKING_TOKENSを下げる・CLAUDE_CODE_MAX_OUTPUT_TOKENSを上げる |
thinking.type.enabled is not supported for this model | 何が起きているかClaude Codeのバージョンがモデルの最小要件より古い | 対処claude update |
unexpected tool_use_id found in tool_result blocks / thinking blocks ... cannot be modified | 何が起きているか会話履歴中のtool_use・tool_result・thinkingブロックの順序がAPIの想定と食い違っている | 対処/rewindで直前のチェックポイントへ戻る |
入力とmax_tokensの合計がコンテキスト上限を超えた場合は、Claude Codeがmax_tokensを減らして再試行します。減らせなくなれば再試行をやめて会話を圧縮します。v2.1.218より前は、思考予算が残りのコンテキストを超えたまま、再試行の回数が尽きるまで同じリクエストを送り直すことがありました。
いずれも「thinkingがらみで応答が止まる」という表面的な症状は近いものの、原因は環境変数の数値関係・CLIバージョン・会話履歴の整合性という異なる層にあります。エラー文の中にmax_tokensとthinking.budget_tokensの数値関係が出ている場合は、本記事が扱う環境変数の設定ミスである可能性が高いと判断できます。
Bedrock・Vertex特有の事情
BedrockやGoogle CloudのAgent Platformでは、リージョンやサービス側の設定によって実効的な出力上限がAnthropic API直接利用時と異なる場合があります。Bedrock・Google CloudのAgent Platform環境の構成・料金差はBedrockのClaude料金ガイドにまとまっています。このエラーに遭遇した場合、まず疑うべきは自分の環境変数設定です。プロバイダー側の障害を先に疑う必要はありません。設定を見直しても解決しない場合に初めて、プロバイダー側の一時的な制約を検討する順番が合理的です。
よくある質問
MAX_THINKING_TOKENS=0にすれば回避できますか
Anthropic APIでは0を指定するとthinking自体を無効化でき、このエラーを根本から避けられます。ただしFable 5はthinkingを無効化できない仕様のため、0を指定しても効果がありません。サードパーティープロバイダー経由では、0はthinkingパラメーター自体を省略する動作になり、adaptive reasoning対応モデルではそれでも思考が行われることがあります。
effortレベルを下げれば直りますか
adaptive reasoning対応モデル(Opus 4.7以降・Sonnet 5・Fable 5)では、effortを下げると思考トークン量が減り、間接的にこのエラーを避けやすくなります。ただし直接的な原因はMAX_THINKING_TOKENSとプロバイダー側の出力上限の関係なので、根本対処にはなりません。なお、Sonnet 4.6時代のmax_tokensをそのまま流用すると別の理由で出力が途中で切れることがあり、こちらはSonnet 5でmax_tokensが途中で切れる問題の対処法で扱っています。
このエラーは絶対に出ませんか
Claude Codeが自動調整するため通常は出ませんが、MAX_THINKING_TOKENSをきわめて高い値に固定し、かつモデルの出力上限自体が小さいケースなど、極端な設定では起こり得ます。まずCLAUDE_CODE_MAX_OUTPUT_TOKENSとMAX_THINKING_TOKENSの両方を明示的に設定していないか確認してください。
CLAUDE_CODE_DISABLE_THINKINGを設定すれば回避できますか
CLAUDE_CODE_DISABLE_THINKINGはthinkingパラメーター自体を省略する互換性オプションです。プロキシやゲートウェイがこのパラメーターを拒否する場合向けの設定です。thinkingを明示的に無効化する目的なら、Anthropic API上ではMAX_THINKING_TOKENS=0のほうが直接的です。いずれの方法でもthinkingにトークンを使わなくなるため回避にはなりますが、根本的な数値関係の設定ミスを直しているわけではありません。
一度環境変数を設定したら、モデルを切り替えるたびに見直すべきですか
はい。MAX_THINKING_TOKENSは特定のモデルを基準に決めた固定値になりがちですが、モデルによって最大出力トークンが128,000と64,000のように倍近く違います。あるモデルで問題なく動いていた設定値を別モデルへそのまま持ち込むと、出力上限が小さいモデル側でだけこのエラーが再発することがあります。設定を環境ごとの固定値にせず、モデル切り替えのたびに見直す運用にしておくと再発を防ぎやすくなります。
まとめ
「Thinking budget exceeds output limit」は、thinkingの予算が出力トークンの上限を超え、実際の回答を書く枠が残っていない状態です。Claude Codeは思考予算を出力上限より小さく自動調整するため、通常は起きません。起きたときは、MAX_THINKING_TOKENSと出力上限の設定値を疑います。対処はMAX_THINKING_TOKENSを下げるかCLAUDE_CODE_MAX_OUTPUT_TOKENSを上げるかのどちらかです。
原因を切り分ける順番は次のとおりです。
MAX_THINKING_TOKENSとCLAUDE_CODE_MAX_OUTPUT_TOKENSの現在値を確認する- 使っているモデルの最大出力トークンと照らし合わせる
- Bedrock・Google CloudのAgent Platform経由ならプロバイダー側の出力上限も疑う