diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md
index 51c866dbe54..844eb23cca4 100644
--- a/docs/src/content/docs/setup/cli.md
+++ b/docs/src/content/docs/setup/cli.md
@@ -279,7 +279,7 @@ gh aw secrets set MY_SECRET --value-from-env MY_TOKEN          # From env var
 
 **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.
 
 ##### `secrets bootstrap`
 
diff --git a/docs/src/content/docs/setup/quick-start.mdx b/docs/src/content/docs/setup/quick-start.mdx
index 8b94a31860c..a9f83adea44 100644
--- a/docs/src/content/docs/setup/quick-start.mdx
+++ b/docs/src/content/docs/setup/quick-start.mdx
@@ -210,7 +210,7 @@ jobs:
     2. Add it as a repository secret from your repository root with `gh secret set ANTHROPIC_API_KEY < /path/to/key.txt`, or use the GitHub UI. See [Authentication](/gh-aw/reference/auth/#anthropic_api_key) for more detail.
 
     :::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).
     :::
   </TabItem>
   <TabItem label="Codex">