Google Cloud credentials expiredの直し方 — Claude Codeの401対処

「Google Cloud credentials expired or invalid」は、Claude CodeがGoogle CloudのAgent Platform(旧Vertex AI)に送ったリクエストが401で返ってきたときに出るエラーです。Agent Platformは認証の期限切れを401で伝えるため、このメッセージは認証情報の更新を促しています。直し方は、どの方式で認証しているかで3通りに分かれます。

このエラーは何を意味するのか

Google Cloudの認証情報が期限切れか、拒否されたことを示します。実際の表示は次の形です。

Google Cloud credentials expired or invalid · refresh your Google Cloud credentials (application default sign-in, or the key file in GOOGLE_APPLICATION_CREDENTIALS) and retry · API Error: 401 ...

中央のヒント部分は環境によって変わります。固定なのは先頭の Google Cloud credentials expired or invalid だけです。検索やログのgrepには、この先頭部分を使うと環境差に左右されません。

v2.1.273より前のClaude Codeは、Agent Platformの401に対して汎用の Please run /login や Failed to authenticate を出していました。この汎用メッセージではGoogle Cloudの認証を更新できないため、現在は専用の文言に分けられています。古い版で「/loginしても直らない」状態になっていたなら、版の古さが原因の可能性があります。

認証方式で直し方が決まる

最初に確認するのは、自分がどの方式でGoogle Cloudに入っているかです。方式ごとに更新する対象が違います。

メッセージに「credentials are managed by this environment」という趣旨のヒントが出ている場合は別扱いです。Claude Codeを起動したアプリが認証情報を持っているため、上の手順は当てはまりません。再試行するか、管理者に連絡します。

ADCで認証しているとき

個人の開発環境では、ADCが最も多い経路です。gcloud でブラウザ認証を済ませた状態が数時間から数日で切れ、それがこのエラーになります。

手動で直す

別のターミナルで次を実行し、ブラウザでのサインインを終えてからClaude Codeで再試行します。

gcloud auth application-default login

gcpAuthRefresh を設定済みなら、メッセージの中に実行すべきコマンドが示されます。そのコマンドを実行しても結果は同じです。

更新を自動化する

毎回の手作業をなくしたいときは、settings.json に gcpAuthRefresh を書きます。Claude Codeが認証切れを検知すると、このコマンドを走らせてからリクエストを再試行します。

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

書き方と挙動の細部は、awsAuthRefreshとgcpAuthRefreshの解説で扱っています。この記事で押さえておきたい点は3つです。

• 実行前に、現在の認証でアクセストークンを要求し、本当に切れているかを確かめます。まだ使えるならコマンドは走りません
• その確認が5秒以内に終わらないときも、コマンドは先に走りません。リクエストが認証エラーで失敗してから実行されます
• コマンドは出力を表示しますが、対話入力は渡せません。ブラウザで認証を終える型に向き、3分以内に終わらなければ打ち切られます

確認がタイムアウトしたときの扱いは、v2.1.261で変わりました。それより前は、タイムアウトを期限切れと見なしていたため、認証が有効でも起動時にブラウザが開くことがありました。

プロジェクトの .claude/settings.json に書いた場合、このキーはフックと同じワークスペース信頼ルールの対象です。-p のセッションでは、一度も信頼していないフォルダでも対象になります。

ゲートウェイ経由のとき

LLM gatewayを通す構成では、Google側の認証を省くために CLAUDE_CODE_SKIP_VERTEX_AUTH を設定します。この変数は、Agent PlatformへのGoogle認証をスキップする設定です。

この構成で401が出たなら、切れているのはGoogleの認証ではなく、ゲートウェイに渡すトークンです。ANTHROPIC_AUTH_TOKEN か ANTHROPIC_CUSTOM_HEADERS の値を新しいものに入れ替えて、再試行します。ここで gcloud auth application-default login を何度実行しても、エラーは変わりません。

見分けるには、環境変数を確認します。

env | grep -E 'CLAUDE_CODE_SKIP_VERTEX_AUTH|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_CUSTOM_HEADERS' | sed 's/=.*/=(set)/'

値を伏せて、設定の有無だけを表示します。CLAUDE_CODE_SKIP_VERTEX_AUTH が出てくれば、ゲートウェイ経由の構成です。

サービスアカウントのキーを使っているとき

GOOGLE_APPLICATION_CREDENTIALS にキーファイルのパスを渡している場合は、そのパスが有効なキーを指しているかを見ます。ファイルが移動していたり、キー自体が無効化されていたりすると、同じ401になります。

この変数は、X.509証明書ベースのWorkload Identity Federationの設定ファイルを指すこともできます。その場合も同じ変数で、確認するのは設定ファイルのパスです。

直ったかをClaude Codeの外で確かめる

更新したのにエラーが繰り返されるときは、同じシェルでClaude Codeの外から認証を試します。

gcloud auth application-default print-access-token > /dev/null && echo OK

OK が出れば、ADCは有効です。出力を捨てているのは、アクセストークンを画面に残さないためです。ここで失敗するなら、原因はClaude Codeではなくgcloud側の認証にあります。成功するのにClaude Codeで401が続くなら、Claude Codeを起動したシェルと確認したシェルで、環境変数やアカウントが違っていないかを疑います。

Claude Codeのセッション内で /status を実行すると、API provider が Google Vertex AI と表示され、GCP project と Default region の行に設定値が出ます。プロバイダーの行が出ないなら、環境変数がプロセスに届いていません。Vertexのセットアップをやり直すなら、/setup-vertexウィザードの手順が早道です。

経路の判定をシェルで済ませる

どの方式で入っているかが分からないときは、環境変数の有無から決めると早く済みます。次のスクリプトは、値を表示せずに経路だけを答えます。

if [ -n "$CLAUDE_CODE_SKIP_VERTEX_AUTH" ]; then
  echo "gateway: ANTHROPIC_AUTH_TOKEN などを更新"
elif [ -n "$GOOGLE_APPLICATION_CREDENTIALS" ]; then
  echo "key file: $GOOGLE_APPLICATION_CREDENTIALS が有効か確認"
else
  echo "ADC: gcloud auth application-default login"
fi

設定ファイルの env ブロックに変数を書いている場合は、シェルには出てきません。その場合は settings.json 側も確認します。Claude Codeに「この環境でGoogle Cloudの認証がどの方式か調べて」と頼む使い方もできますが、トークンの値をそのまま出力させない指示を添えておくと安全です。

版ごとの挙動の違い

このエラー周りは、直近の版で何度か挙動が変わっています。古い版で見える症状と照らすと、版を上げるだけで済むかが分かります。

非対話実行やCIで出たとき

-p での実行やCIでは、ブラウザでのサインインを完了できません。gcpAuthRefresh のコマンドは対話入力を受け取れないため、ブラウザ認証を要求する型は向きません。この場合は、キーファイルかWorkload Identity Federationの設定ファイルを GOOGLE_APPLICATION_CREDENTIALS で渡す構成が現実的です。キーが失効したときは、パスの先を差し替えれば同じ手順で直ります。

セッション内の /login から「3rd-party platform」を選び、Google Vertex AIを選ぶと、認証方式を選び直すウィザードが開きます。ADC、サービスアカウントのキーファイル、環境にある認証情報のどれを使うかを決め直せます。選んだ結果は、ユーザー設定の env ブロックに保存されます。

似たメッセージとの見分け方

Google Cloud関連の認証エラーは3種類あり、直し方が違います。

403の Google Cloud authentication failed は、Agent Platformが期限切れではなく認可の拒否に使うステータスです。多くは、認証に使うIDにIAM権限がないか、プロジェクトでモデルが有効になっていません。Claude Code用のロールは roles/aiplatform.user で、必要な権限は aiplatform.endpoints.predict です。手順はVertex AIのIAM設定とチーム展開にあります。

Could not load Google Cloud credentials は、リクエストがクラウドに届く前の失敗です。invalid_grant や Could not load the default credentials といった詳細が続きます。-p の非対話実行とAgent SDKでは、構造化されたエラーコードが cloud_credential_error になります。この名前は、スクリプトから判定するときに使えます。

自動リトライと表示のタイミング

Google Cloudの認証情報が期限切れか欠けているとき、Claude Codeはキャッシュした認証情報を捨てて、最大2回まで再試行します。それでも直らなければエラーを出すので、すぐに再認証へ進めます。v2.1.228より前は、リトライの上限いっぱいまで再試行してから表示していました。

古い版で「エラーが出るまでやけに待たされる」場合は、この挙動が原因かもしれません。

直らないときのチェックリスト

上から順に確認します。

1. メッセージの先頭が Google Cloud credentials expired or invalid か。authentication failed(403)なら、IAMの問題です
2. ゲートウェイ経由か。CLAUDE_CODE_SKIP_VERTEX_AUTH があれば、ゲートウェイのトークンを更新します
3. gcloud auth application-default print-access-token が成功するか
4. Claude Codeを起動したシェルで、GOOGLE_APPLICATION_CREDENTIALS が意図したキーを指しているか
5. 版がv2.1.273以降か。古いと汎用メッセージが出て、切り分けができません

リージョン設定の食い違いは、認証エラーとは別の症状として出ます。CLOUD_ML_REGION の挙動はVertex AIのリージョン設定で扱っています。AWS側で同じ症状に当たったときは、AWS credentials expired or invalidの直し方が対応します。

まとめ

401のこのエラーは、期限切れの対象がどこかを当てれば直ります。ADCならgcloudのサインイン、ゲートウェイならゲートウェイのトークン、キーファイルならそのパスです。更新後は gcloud auth application-default print-access-token で、Claude Codeの外から確かめられます。繰り返すなら gcpAuthRefresh を設定し、手作業を省く選択肢があります。