Extra inputs are not permitted — Claude Codeの原因と対処

Claude Codeを社内プロキシやLLMゲートウェイ経由で使っていると、API Error: 400 ... Extra inputs are not permittedで止まることがあります。原因の筆頭は、ゲートウェイがanthropic-betaヘッダーを転送していないことです。ただしヘッダーを通していても起きる経路があり、エラーに出るフィールド名を見ると切り分けられます。

「Extra inputs are not permitted」が出る仕組み

Claude Codeはcontext_managementやeffortのようなベータ限定フィールドを、それらを有効化するanthropic-betaヘッダーと一緒にAPIへ送ります(context_managementのclear_tool_uses_20250919エディットが持つtrigger・keep等5つの設定オプションもこのベータの対象です)。ヘッダーとボディはペアで動く設計です。

ゲートウェイがボディだけを通してヘッダーを落とすと、APIは対応するヘッダーのないフィールドを受け取り、400で拒否します。逆に両方が同時に消えた場合は、エラーにならず機能が静かにオフになります。

代表的なエラー文字列は、フィールド名まで示される400です。

API Error: 400 ... Extra inputs are not permitted ... context_management

ヘッダー自体の値が拒否されるときは、anthropic-betaヘッダーについてのUnexpected value(s)エラーになります。こちらは、ゲートウェイや上流がヘッダーの値そのものを受け付けないときに出ます。どちらにも、同じ環境変数が回避策として案内されています。

ゲートウェイで壊れ方は2通りある

ヘッダーとボディの組が崩れるこの型の400は、間に社内プロキシ・LLMゲートウェイ・企業向けAPIゲートウェイが挟まる構成で起きます。Claude Codeを直接Anthropic APIにつないでいる構成は、この型の対象外です。壊れ方は2通りあり、直し方が変わります。

公式のゲートウェイ互換性ガイドは、anthropic-betaの値を個別に許可リストへ載せないよう求めています。値の集合がClaude Codeのリリースごとに変わるためです。リクエストの中身を検査するためにボディを書き換えたり伏せ字にしたりするゲートウェイも、ペアを壊す点で同じ結果になります。検査は書き換えずに行うのが前提です。

エラーに出るフィールド名から原因を絞る

メッセージに含まれるフィールド名が、どの機能のペアが崩れたかの手がかりになります。次の表は公式の機能別対応表を、エラー文字列から引ける形に組み替えたものです。

thinkingの拒否はこの環境変数の守備範囲外です。第一の対処は上流の更新です。

thinkingを拒否されたときは、Claude Code側も再試行します。拒否された機能は、その会話の残りで無効になります。Opus 4.6とSonnet 4.6に限り、CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1でも逃がせます。この変数は、Fable・Sonnet 5以降・Opus 4.7以降には効きません。

output_config.effortの拒否は、Claude Code側にも自動回復があります。output_config.effortとExtra inputs are not permittedが並ぶ400を受けると、effortを外して再試行し、そのモデルへの以降のリクエストでは終了まで送りません。context_managementとツールスキーマの拒否には再試行が働かないため、この2つは400がそのまま利用者に届きます。

この再試行は、上流のエラー文言を照合して発動します。ゲートウェイが上流のエラーを独自の形式で包み直すと、ステータスコードが同じでも回復が働かなくなります。エラー本文は書き換えずに返す設定が前提です。例外として、包んだエラーのメッセージにcapability_rejected:という安定したトークンが入っていれば、回復は働きます。

output_configの拒否は、Amazon BedrockやGoogle Cloudの上流に流している構成で目立つと公式は書いています。型2に当たる典型例で、ヘッダーを通すだけでは直らず、フィールドの送信側を止める必要があります。

対処法1: ゲートウェイでanthropic-betaヘッダーを転送する

管理者権限があるなら、まずゲートウェイの設定を見直します。anthropic-versionとanthropic-betaを変更せずに通せば、Claude Codeは通常どおりベータ機能を含むリクエストを送れます。社内の複数チームが同じゲートウェイを使っている場合、この変更が最も影響範囲の広い解決策です。

サブスクリプションのログイン(claude.aiアカウント)のままANTHROPIC_BASE_URLだけを設定している場合は、ヘッダーに上流が要求するOAuth用の値も含まれます。これを落とすと、400ではなく401で失敗します。

対処法2: CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASで送らないようにする

ゲートウェイの設定を変更する権限がない、あるいはすぐに変更できない場合は、Claude Code起動前に環境変数を設定します。

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude

この変数は、ベータ専用の値を取り除くスイッチです。取り除くものと残るものを分けると、次のとおりです。

自分で足した値が原因のエラーは、ANTHROPIC_BETASやCLAUDE_CODE_EXTRA_BODYの設定側から該当の値を外して確かめます。

手元のv2.1.286でclaude --helpを引くと、同じ系統のオプションとして--betasが見つかります。

claude --version
claude --help | grep -A1 -e "--betas"

2.1.286 (Claude Code)
  --betas <betas...>                    Beta headers to include in API requests
                                        (API key users only)

説明に「API key users only」とある点に注意が必要です。サブスクリプションのログインでは、このオプションでベータ値を足す使い方はできない仕様です。

この設定のトレードオフ — MCPツール検索が無効になる

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1を設定すると、MCPツール検索(MCP tool search)が無効になり、全てのMCPツールが最初から読み込まれます。MCPサーバーを多数接続しているプロジェクトでは、この副作用でコンテキストの消費量が増えることがあります。

ここで見落としやすいのが、そもそもゲートウェイ経由だとツール検索の既定がオフという点です。ANTHROPIC_BASE_URLがAnthropic本体以外のホストを指すと、ツール検索は既定で無効になります。プロキシがtool_referenceブロックを転送できるなら、ENABLE_TOOL_SEARCH=trueで有効にできます。この環境変数が実際に失うのは、そうして有効にしていた構成のツール検索です。

v2.1.227以降なら、組織がmanaged settingsを使ってツール検索を有効なまま保てます。そのとき何が送られるかは接続方法しだいです。

• 直接接続、またはANTHROPIC_BASE_URLのゲートウェイ経由: ツール検索のベータヘッダー・defer_loading・tool_referenceを送り続け、残りを取り除く
• クラウドプロバイダー経由、またはClaude appsゲートウェイでのサインイン: この上書きは効かない

ゲートウェイ以外でも出るときは別の原因を疑う

この変数が効くのは、ゲートウェイでヘッダーとボディの組が崩れるケースです。ゲートウェイを使っていない(直接接続やVertex AI)のに同じ文言が出るなら、Claude Code自体のリクエスト生成が関わっている可能性があります。GitHubのanthropics/claude-codeリポジトリには、フィールド名違いの同文言の報告があります。

• #68797: 直接接続で、サブエージェントの起動時にthinking.disabled.displayがExtra inputs are not permittedになる(v2.1.183で修正済み)
• #82539: Vertex AIでdiagnosticsが同じエラーになる(放置による自動クローズで、修正の記載は見当たらない)
• #84114: Vertex AI経由のコンパクション時にmessages.N.content.M.text.parsed_outputが拒否される(オープン)

いずれもタイトルに載るフィールド名がベータヘッダーとは別物です。名前がcontext_managementでもoutput_configでもないときは、ゲートウェイ設定より先にClaude Codeのバージョンを疑う価値があります。バージョンの確認・固定・ダウングレード手順が使えます。似た原因系統のエラーに、認証値そのものにヘッダーへ使えない文字が混ざる「Invalid request header value」エラーがあります。落ちる対象がベータヘッダーか認証ヘッダーかで、切り分けが変わります。同じ「スキーマが通らない」系でも、--json-schemaに渡した定義そのものが弾かれるケースは「--json-schema value is not a valid JSON Schema」の直し方で扱っています。

許可リスト式のゲートウェイは新リリースで再発する

Claude Codeはリリースを重ねるごとに、新しいanthropic-betaの値や新しいボディ項目、ときには新しいanthropic-*・x-claude-code-*ヘッダーを足していきます。見えている値だけを許可するゲートウェイは、次の機能が入ったリリースで同じ症状を起こします。公式が「現在見えている値で固定せず、新しいリリースでゲートウェイを試すこと」を求めているのはこのためです。

ある日突然、同じ設定のまま特定のバージョンから失敗し始めたなら、この型を疑えます。

よくあるつまずき

ENABLE_TOOL_SEARCHを設定しているのにツール検索が効かない、という形で表に出ることもあります。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1が有効だと、組織がmanaged settingsで保っていない限り、ツール検索は無効のままです。両方を設定していると矛盾に気づきにくいので、片方を外した状態で確かめます。

応急処置を外すまでの手順

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1は恒久設定ではなく、ゲートウェイの修正待ちの間だけ使う位置づけです。外し忘れを防ぐ順序は次のとおりです。

よくある質問

自分がゲートウェイ経由かどうかを確認する方法はありますか

ANTHROPIC_BASE_URLが設定されているかを確認します。社内のプロキシやゲートウェイ経由でのアクセスを案内されていないかも見ます。心当たりがなければ直接接続の可能性が高いです。社内プロキシの設定手順はClaude Codeプロキシ設定にまとめています。

Claude Codeをアップデートすれば直りますか

ゲートウェイ側の処理が原因なら、Claude Codeだけを上げても再発します。context_managementとツールスキーマの拒否には、Claude Code側の自動再試行も働きません。一方で、前節の#68797のように、Claude Code側の修正で解消した例もあります。フィールド名で見分けます。

まとめ

このエラーは「ゲートウェイがヘッダーを落としたのか、上流がフィールドを知らないのか」を、エラーに出るフィールド名で切り分けるのが近道です。環境変数は応急処置にすぎず、直らないときはフィールド名の見立てに戻るのが確実です。