Extra inputs are not permitted — Claude Codeの原因と対処
ゲートウェイ経由で出る「Extra inputs are not permitted」の原因と、ヘッダー転送設定・環境変数での対処法をまとめます。
Claude Codeを社内プロキシやLLMゲートウェイ経由で使っていると、API Error: 400 ... Extra inputs are not permittedで止まることがあります。原因はゲートウェイがanthropic-betaヘッダーを転送していないことで、Claude Code側の設定ミスではありません。
「Extra inputs are not permitted」が出る仕組み
Claude Codeはcontext_managementやeffortのようなベータ限定フィールドを、それらを有効化するanthropic-betaヘッダーと一緒にAPIへ送ります。プロキシやLLMゲートウェイがリクエストボディはそのまま転送しつつ、このヘッダーだけ落としてしまうと、APIはヘッダーに紐づかない未知のフィールドを受け取ることになり、400エラーで拒否します。
実際に出るエラー文字列は2パターンあります。
API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` headerどちらも根は同じで、ヘッダーとボディの不一致です。前者はフィールド名まで具体的に示され、後者はヘッダー自体の値が想定外だと指摘します。
原因はゲートウェイのヘッダー転送設定
Claude Codeを直接Anthropic APIに接続している場合、このエラーは基本的に起きません。発生するのは、Claude Codeとの間に社内プロキシ・LLMゲートウェイ・企業向けAPIゲートウェイが挟まっている構成です。こうしたゲートウェイは、標準的なヘッダーは転送しつつ、Anthropic固有のanthropic-betaヘッダーをフィルタリングしてしまう設定になっていることがあります。
対処は2段構えです。恒久対応はゲートウェイ側の設定変更、応急処置はClaude Code側でベータ機能を送らないようにする方法です。
対処法1: ゲートウェイでanthropic-betaヘッダーを転送する
管理者権限があるなら、まずゲートウェイの設定を見直します。anthropic-betaヘッダーをそのまま通過させるようにすれば、Claude Codeは通常どおりベータ機能を含むリクエストを送れます。社内の複数チームが同じゲートウェイを使っている場合、この設定変更が最も影響範囲の広い解決策です。
対処法2: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASで送らないようにする
ゲートウェイの設定を変更する権限がない、あるいはすぐに変更できない場合は、Claude Code起動前に環境変数を設定します。
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claudeこの変数を1にすると、Claude Codeはanthropic-betaヘッダーと、defer_loading・eager_input_streamingのようなベータ限定のツールスキーマフィールドをリクエストから取り除きます。name・description・input_schema・cache_controlといった標準フィールドは変わらず送られるため、ツール呼び出し自体は機能し続けます。
この設定のトレードオフ — MCPツール検索が無効になる
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1を設定すると、MCPツール検索(MCP tool search)が無効になり、ENABLE_TOOL_SEARCHを設定していても全てのMCPツールが最初から読み込まれます。MCPサーバーを多数接続しているプロジェクトでは、この副作用でコンテキストの消費量が増えることがあります。v2.1.227以降であれば、managed settingsを使うことでツール検索を有効なまま保てます。組織で一括設定する場合は、managed settingsでの制御も検討します。
発生しやすい環境の特徴
このエラーが起きるのは、Claude Codeを直接使っている個人開発者ではなく、社内の複数チームが共通のプロキシやLLMゲートウェイ経由でAnthropic APIにアクセスしている組織です。ゲートウェイは通常、リクエストのログ収集・レート制限・利用状況の可視化を目的に導入されますが、これらの機能はAnthropic固有のベータヘッダーを想定していないことが多く、標準的なヘッダーだけを転送するデフォルト設定のままだと今回のエラーに行き着きます。
Claude Code自体が新しいベータ機能(context_managementやeffort)を使うようになるたびに、ゲートウェイ側の許可リストが追いついていないと同じ症状が再発する構造でもあります。
よくあるつまずき
ローカルの環境変数だけ設定して満足してしまうケースがあります。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1は自分の端末でしか効かないため、チーム全員が同じゲートウェイ経由でエラーに遭遇している場合、1人ずつ環境変数を設定するより、ゲートウェイ側かmanaged settingsでの一括対応の方が運用コストが低くなります。
環境変数を外し忘れると、MCPツール検索が無効なままになり、意図せずコンテキスト消費が増え続けます。ゲートウェイ側の修正が完了した後も端末に変数が残っている限り、この状態は自然には解消しません。設定した本人も、時間が経つと「なぜENABLE_TOOL_SEARCHを設定しているのに効かないのか」と別の症状として捉え直してしまい、根本原因が環境変数の外し忘れだと気づくまでに時間がかかることがあります。定期的に自分の環境変数一覧を見直す習慣をつけておくと、こうした取りこぼしに早く気づけます。
ENABLE_TOOL_SEARCHを設定しているのに効かないと困るケースもあります。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1が設定されていると、この変数の値に関わらずツール検索は無効になります。両方を設定している場合は矛盾に気づきにくいので注意します。
症状別の見分け方早見表
| 症状 | 該当する原因 | 対処 |
|---|---|---|
Extra inputs are not permitted(フィールド名付き) | 該当する原因ゲートウェイがヘッダーを落としボディだけ転送 | 対処ゲートウェイ設定変更 / 環境変数で応急処置 |
Unexpected value(s) for the anthropic-beta header | 該当する原因ヘッダー自体が想定外の値で届く | 対処同上(ゲートウェイのヘッダー処理を確認) |
| 直接API接続でも同じエラーが出る | 該当する原因ゲートウェイ経由ではない可能性が高い | 対処Claude Codeのバージョンを確認しアップデート |
直接Anthropic APIに接続しているのに同じエラーが出る場合は、ゲートウェイの問題ではなく別の原因(古いバージョンでの既知の不具合等)を疑い、Claude Codeバージョンの確認・固定・ダウングレード手順を参考にアップデートを検討します。似た原因系統のエラーに、認証値そのものにヘッダーへ使えない文字が混ざる「Invalid request header value」エラーがあります。どちらもゲートウェイ・プロキシがヘッダーに手を加えることで起きる点は共通しますが、落ちる対象がベータヘッダーか認証ヘッダーかで切り分けが変わります。同じ「スキーマが通らない」系でも、--json-schema に渡した定義そのものが弾かれるケースは「--json-schema value is not a valid JSON Schema」の直し方で扱っています。
この応急処置をいつ外すか
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1は恒久設定ではなく、ゲートウェイの修正待ちの間だけ使う位置づけです。次の順序で運用すると、外し忘れを防げます。
- エラーが出た時点で、まず個人の端末にこの環境変数を設定してブロックを解除する
- 並行してゲートウェイ管理者に
anthropic-betaヘッダーの転送設定を依頼する - ゲートウェイ側の設定変更が反映されたら、環境変数を削除して再起動し、エラーが再発しないことを確認する
- チーム全体で同じ症状が出ていた場合は、個々の端末の環境変数ではなくmanaged settingsでの一括制御に切り替える
3の確認を飛ばして環境変数を残したままにすると、MCPツール検索が無効な状態がそのまま定着し、後になって「なぜかMCPツールの読み込みが遅い」という別の問題として再浮上することがあります。
よくある質問
直接Anthropic APIに接続していても起きますか
基本的には起きません。このエラーはヘッダーとボディの不一致が原因で、ヘッダーを落とす処理を挟む中間層(プロキシ・ゲートウェイ)がなければ発生しにくい種類のエラーです。
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASは他の機能にも影響しますか
はい。MCPツール検索が無効になり、接続している全MCPツールが最初から読み込まれます。ツール数が多い環境ではコンテキスト消費が増える点に注意します。
自分がゲートウェイ経由かどうかを確認する方法はありますか
ANTHROPIC_BASE_URLが設定されているか、あるいは社内のプロキシ・ゲートウェイ経由でのアクセスを案内されているかを確認します。設定や社内ドキュメントに心当たりがなければ、直接接続の可能性が高いです。社内プロキシの設定手順はClaude Codeプロキシ設定にまとめています。
組織全体でこの環境変数を設定できますか
managed settingsで組織全体に配布できます。個々の開発者に環境変数の設定を依頼する代わりに、Claude Code組織管理ガイドの手順で一括設定する方法もあります。
エラーメッセージにcontext_management以外のフィールド名が出ることもありますか
あります。ベータ限定フィールドはバージョンアップのたびに増えることがあり、context_managementやeffort以外の名前がエラーに含まれる場合もあります。フィールド名が変わっても、原因と対処(ヘッダー転送設定、または応急処置の環境変数)は同じです。
エラーが出たり出なかったりするのはなぜですか
context_managementやeffortなどベータ限定フィールドを使うリクエストのときだけヘッダーが必要になるため、それらを使わないリクエストでは問題が表面化しません。断続的に見える場合、リクエストの種類によって症状の有無が変わっている可能性があります。
個人のAPIキーで直接使えば回避できますか
ゲートウェイを経由せずAnthropic APIに直接接続できる環境であれば回避できます。ただし多くの企業ではセキュリティ・課金管理の都合でゲートウェイ経由の接続が必須になっているため、現実的な解決策としてはゲートウェイ側の設定変更を依頼するほうが優先度が高くなります。
Claude Codeをアップデートすれば直りますか
直りません。原因はClaude Code側ではなくゲートウェイ側のヘッダー処理にあるため、Claude Codeだけをアップデートしても再発します。バージョンアップと合わせて、ベータ機能を使うリクエストが増えていないかも確認すると、症状の変化を説明しやすくなります。
まとめ
「Extra inputs are not permitted」は、Claude Codeとゲートウェイの間でanthropic-betaヘッダーが落ちることが原因です。恒久対応はゲートウェイ側でのヘッダー転送設定、権限がない場合の応急処置はCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1です。ただし後者はMCPツール検索を無効にする副作用があるため、ゲートウェイ側の設定が直り次第、外すのが基本の運用になります。