Document CLAUDE_CODE_OAUTH_TOKEN failure mode in setup docs - #54590
Merged
pelikhan merged 2 commits intoAug 21, 2026
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Document CLAUDE_CODE_OAUTH_TOKEN failure mode
Document CLAUDE_CODE_OAUTH_TOKEN failure mode in setup docs
Aug 21, 2026
pelikhan
approved these changes
Aug 21, 2026
pelikhan
marked this pull request as ready for review
August 21, 2026 18:39
pelikhan
deleted the
copilot/deep-report-document-claude-code-oauth-token-failu
branch
August 21, 2026 18:39
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the failure mode when unsupported Claude OAuth tokens are used.
Changes:
- Adds troubleshooting guidance to quick-start documentation.
- Mirrors the guidance in the CLI reference.
Show a summary per file
| File | Description |
|---|---|
docs/src/content/docs/setup/quick-start.mdx |
Expands the Claude authentication note. |
docs/src/content/docs/setup/cli.md |
Adds unsupported-token failure guidance. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 2
- Review effort level: Balanced
| **Options:** `--repo/-r`, `--value`, `--value-from-env`, `--api-url` | ||
|
|
||
| For Claude workflows, set `ANTHROPIC_API_KEY` or configure [Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif). `CLAUDE_CODE_OAUTH_TOKEN`, including a token from `claude login`, is not supported. | ||
| For Claude workflows, set `ANTHROPIC_API_KEY` or configure [Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif). `CLAUDE_CODE_OAUTH_TOKEN`, including a token from `claude login`, is not supported; it is silently ignored, so the run instead fails with an authentication error from the Claude CLI that never mentions the token, which is the signal to switch credentials. |
|
|
||
| :::note | ||
| Claude subscription OAuth tokens (`CLAUDE_CODE_OAUTH_TOKEN`) are not supported and are ignored if set. Use `ANTHROPIC_API_KEY` or [Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif). | ||
| Claude subscription OAuth tokens (`CLAUDE_CODE_OAUTH_TOKEN`) are not supported and are ignored if set. If it is the only credential configured, the workflow fails with an authentication error from the Claude CLI (for example, a missing/invalid API key error) rather than any message mentioning `CLAUDE_CODE_OAUTH_TOKEN` — treat that failure as a signal to switch to `ANTHROPIC_API_KEY` or [Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif). |
Contributor
|
🎉 This pull request is included in a new release. Release: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs stated
CLAUDE_CODE_OAUTH_TOKEN"is not supported and is ignored if set" but never described what a user actually sees when they try it — a Claude Code CLI user with this token fromclaude loginhad no way to recognize the symptom without debugging blind.Changes
docs/src/content/docs/setup/quick-start.mdx: extended the existing note to state that when the token is set withoutANTHROPIC_API_KEY/WIF, the run fails with a generic Claude CLI authentication error that never mentions the token itself.docs/src/content/docs/setup/cli.md: added the same clarification inline after the existing "is not supported" statement.Both point users to treat that unrelated auth failure as the signal to switch to
ANTHROPIC_API_KEYor Anthropic WIF, rather than debugging the reported error at face value.