「Invalid request header value」エラーの原因と対処 — Claude Code

「Invalid request header value」は、認証情報として送ろうとした値にHTTPヘッダーが運べない文字が含まれているときに出ます。改行・NULバイト・U+00FFより上のコードポイントの文字(カーリークォートやゼロ幅スペースなど)が対象です。Claude Codeはリクエストを送る前に止め、原因の変数か設定名をメッセージに含めて表示します。

どの文字が引っかかるのか

このチェックの対象は3種類です。改行(line break)、NULバイト、U+00FFを超えるコードポイントの文字。カーリークォート(スマート引用符)やゼロ幅スペース、BOM(バイトオーダーマーク)はこの3つ目に含まれます。

典型的な原因は、ドキュメントやチャットからコピーした認証情報です。エディタやチャットアプリが自動でストレートクォートをカーリークォートに変換していたり、コピー元に見えない改行やゼロ幅スペースが混ざっていたりすると、貼り付けた値がそのままではHTTPヘッダーとして送れなくなります。

メッセージの前半でどの設定が原因か分かる

メッセージは·(中黒)で区切られた構成になっていて、最初の部分が原因の変数を示します。

ANTHROPIC_CUSTOM_HEADERSが原因のときは、Name: Valueのペアのうち何番目が問題かも示されます。「distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS」のように、名前や値そのものは繰り返さずペアの位置だけを数えて教えてくれる形式です。このチェックはv2.1.227以降で有効です。

メッセージの文字位置をどう読むか

説明部分は固定のフレーズと文字数の組み合わせで作られていて、値そのものが漏れることはありません。位置は1文字目から数えます。

Invalid auth token · Fix external auth token · Invalid Authorization header value from ANTHROPIC_AUTH_TOKEN: it contains a line break at character 41 (120 characters on 2 lines).

この例なら、41文字目に改行があり、全体は2行にわたる120文字だったと分かります。問題の文字がBOM・ゼロ幅スペース・カーリークォートのようなよく知られた不可視文字か記号のときだけ名指しされ、それ以外はa non-ASCII characterとだけ表示されます。値そのものを推測できる情報は含まれません。

このチェックが動く場面・動かない場面

チェックが走るのは、Claude APIへ直接リクエストを送るときと、LLMゲートウェイ経由のときです。Amazon Bedrockのようなサードパーティのクラウドプロバイダー経由では、送信前のこのチェックは実行されません。

似た入り口を持つ他のエラーとの関係も押さえておくと切り分けが速くなります。apiKeyHelperスクリプトの出力はこのチェックを一切通りません。スクリプト実行時に別途検証され、HTTPヘッダーが運べない出力を返した場合は「Your apiKeyHelper script is failing」として表示されます。保存済みの/login情報が不正な場合も、このエラーではなく「Not logged in」として扱われ、/loginのやり直しを促されます。ゲートウェイがヘッダー自体を落としてしまうケースでは、値の中身ではなくanthropic-betaヘッダーの欠落が原因になり、「Extra inputs are not permitted」の原因と対処という別のエラーとして表面化します。

ANTHROPIC_CUSTOM_HEADERSを書くときの正しい形式

ANTHROPIC_CUSTOM_HEADERSは、複数のヘッダーを設定するときに改行区切りでName: Valueの形式を守る必要があります。

# 1行に1ペア。複数ヘッダーは改行で区切る
export ANTHROPIC_CUSTOM_HEADERS="X-Team-Id: platform
X-Request-Source: internal-tool"

ここに全角記号や、コピー元でカーリークォートへ自動変換された"が混ざると、該当ペアの位置がエラーに出ます。書き直すときは、同じ貼り付け元から再度コピーするのではなく、報告された位置の周辺だけを手で打ち直すのが確実です。同じソースから再度コピーすると、同じ不可視文字を再び持ち込むことがあります。

発生パターンが偏る原因

このエラーが集中して起きる場面には共通点があります。値の出どころが「人が読む文書」を経由しているケースです。

チャットアプリやWord・Google Docsのようなワープロソフトは、ストレートクォート(")を自動でカーリークォート(" ")に変換する機能を既定で持っています。認証トークンやカスタムヘッダーの値をこうした文書からコピーしてターミナルに貼り付けると、見た目では区別がつかないままU+00FFを超える文字が混入します。社内のオンボーディング手順書やチャットのDMで認証情報を共有している組織ほど、このパターンで詰まりやすくなります。

もう1つの温床はOS間でのコピー&ペーストです。WindowsのクリップボードはCRLFの改行を保持したままターミナルへ渡すことがあり、macOS・Linux側のLF前提のツールと組み合わせたときに「1行のつもりが2行として数えられる」状態を作ります。シークレット管理ツールのCLI出力をそのままコピーする場合も、出力の末尾に付く改行文字ごと貼り付けてしまうと同様の症状が出ます。値を扱うときは、コピー&ペーストを1段階減らし、CLIの出力を直接環境変数へ流し込む(シェルのコマンド置換を使うなど)ほうが、目に見えない文字の混入を防ぎやすい方法です。

チーム開発では、この種の値をREADMEやWiki、チャットのピン留めメッセージで共有していることも多く、一度カーリークォート化された値がそのまま社内の「正解」として使い回され続けるケースもあります。エラーが出た本人だけでなく、同じ手順書からコピーした他のメンバーにも同じ症状が出ていないかを確認すると、手順書側の記載を直すところまで踏み込んで根治できます。

直し方の手順

メッセージが名指しした変数か設定を、報告された位置の周辺だけ手で打ち直して再設定します。ANTHROPIC_CUSTOM_HEADERSなら、該当するName: Valueのペアだけを書き直します。設定後は/statusで、想定した認証情報のソースが実際に有効になっているかを確認します。環境変数の中身を目視で確認したい場合は、env | grep ANTHROPIC(PowerShellならGet-ChildItem Env:ANTHROPIC*)で現在の値を洗い出せます。この方法はdirenvやdotenvプラグイン、IDE内蔵ターミナルが.envファイルから意図せず古い値を読み込んでいるケースの発見にも使えます。環境変数まわりの設定箇所はClaude Code環境変数リファレンスにまとめています。

ANTHROPIC_AUTH_TOKENが原因の場合は、ベアラートークンとして送る値そのものを疑います。LLMゲートウェイやプロキシ経由で認証している構成では、ゲートウェイ側が発行したトークンをコピーする工程が長くなりがちで、それだけ不可視文字が混入する機会も増えます。ゲートウェイ経由の認証方式や、ANTHROPIC_API_KEYとの使い分けはClaude Codeログイン方法3種の使い分けで扱っています。トークンや設定ファイルの管理場所を整理し直したい場合は、Claude Code settings.json完全ガイドのenvブロックの項目もあわせて確認すると、どこで値を一元管理すべきかが見えてきます。

よくある質問

エラーメッセージに問題の文字そのものは書かれていますか

書かれません。説明はすべて固定フレーズと文字数の組み合わせで構成され、値そのものは一切含まれません。文字を特定できるのは、BOM・ゼロ幅スペース・カーリークォートのようなよく知られた不可視文字か記号のときだけで、それ以外はa non-ASCII characterとだけ表示されます。

改行を含むトークンをどう見分ければいいですか

メッセージに「character 41 (120 characters on 2 lines)」のように、位置と行数が示されます。エディタで貼り付けた値を表示し、報告された位置の前後にカーソルを置いて改行や不可視文字が無いか確認するのが早道です。ターミナルによっては改行が見た目に出ないことがあるため、目視だけに頼らず該当箇所を打ち直すほうが確実です。

Bedrock経由でも同じチェックは働きますか

働きません。このチェックはClaude APIへ直接送るときとLLMゲートウェイ経由のときに実行され、Amazon Bedrockなどサードパーティのクラウドプロバイダー経由では送信前に実行されません。同じ不正な値を設定していても、プロバイダーによってエラーの出方が変わります。

なぜ貼り付けたときにはエディタで正常に見えるのですか

カーリークォートやゼロ幅スペースの多くは、通常のフォントでは通常の文字とほとんど区別できない見た目で描画されます。エディタやターミナルは文字コードの違いを表示上区別しないことが多いため、目視でのチェックはすり抜けやすい方法です。疑わしい値は、テキストエディタの「不可視文字を表示」機能を使うか、いったん値をコマンドの引数として渡して文字数を数えるほうが確実に見つかります。

Invalid API keyと何が違いますか

原因の入り口が違います。ANTHROPIC_API_KEYがこのヘッダーチェックに引っかかった場合はメッセージがInvalid API keyとして表示され、Invalid request header valueは出ません。一方でキー自体は形式として正しいのにAPI側が拒否した場合もInvalid API keyになるため、この2つは同じ表示の裏に異なる原因が混在します。

まとめ

「Invalid request header value」は、認証値にHTTPヘッダーが運べない文字が混ざったときに、送信前の時点で止まって出るエラーです。メッセージの前半でどの変数が原因か、後半で文字の位置がそれぞれ分かる形式になっています。直し方は、報告された位置の周辺を貼り付けではなく手で打ち直すことです。apiKeyHelperの出力や保存済みログイン情報が原因のときは、このエラーではなく別のメッセージとして表示される点も、切り分けの手がかりになります。