「Thinking budget exceeds」エラーの原因と対処法(Claude Code)
「Thinking budget exceeds output limit」はMAX_THINKING_TOKENSが出力上限を超えたときに出ます。Bedrock・Vertex利用者に多い原因と環境変数での直し方をたどります。
「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がリクエストごと拒否します。
Anthropic APIでは基本的に起きない
Claude Codeは、直接のAnthropic API利用時にはこの2つの値を自動的に調整します。MAX_THINKING_TOKENSを明示的に指定していても、Claude Code側が出力上限とのバランスを取ってリクエストを組み立てるため、通常はこのエラーに遭遇しません。
このエラーが典型的に出るのは、Amazon BedrockかGoogle CloudのAgent Platformを経由しているときです。これらのプロバイダーでは、MAX_THINKING_TOKENSを出力上限より高く設定した場合や、plan modeが思考予算を引き上げた場合に自動調整が効きません。結果としてエラーがそのまま表面化します。
まず現在の設定値を確認する
対処に入る前に、自分の環境で両方の値がどう設定されているかを確認します。どちらか一方だけ設定していて、もう一方は既定値のままというケースも多いため、まず現状を正確に把握してから対処法を選ぶのが近道です。設定ファイルや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つも残りません。BedrockやGoogle CloudのAgent Platform経由の場合は、この2つの値の関係をClaude Code側が自動では調整しない点も踏まえて確認してください。
対処法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トークンを下回らない」よう自動でキャップします。ただしこの自動キャップはAnthropic API直接利用時の挙動で、Bedrock・Google CloudのAgent Platform経由では前述のとおり効きません。
対処法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 | 最大出力トークン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で直前のチェックポイントへ戻る |
いずれも「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とプロバイダー側の出力上限の関係なので、根本対処にはなりません。
plan modeを使わなければ出ませんか
plan modeがthinking予算を引き上げる仕様のため、plan mode下で出力上限ぎりぎりの設定をしているとエラーが表面化しやすくなります。plan modeを使わない場合でも、MAX_THINKING_TOKENSを出力上限に近い値へ手動で設定していれば同じエラーになり得ますので注意してください。
Anthropic API直接利用でもこのエラーは絶対に出ませんか
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の予算が出力トークンの上限を超え、実際の回答を書く枠が残っていない状態です。Anthropic API直接利用では自動調整が働きます。主にBedrock・Google CloudのAgent Platformで、MAX_THINKING_TOKENSを出力上限より高く設定したときに起こります。対処はMAX_THINKING_TOKENSを下げるかCLAUDE_CODE_MAX_OUTPUT_TOKENSを上げるかのどちらかです。
原因を切り分ける順番は次のとおりです。
MAX_THINKING_TOKENSとCLAUDE_CODE_MAX_OUTPUT_TOKENSの現在値を確認する- 使っているモデルの最大出力トークンと照らし合わせる
- Bedrock・Google CloudのAgent Platform経由ならプロバイダー側の出力上限も疑う
- plan modeを使っている場合はその影響も考慮する