[DOCS] Auth login troubleshooting missing pasted OAuth code fallback for localhost callback failures

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/troubleshoot-install

Section/Topic

"OAuth login fails in WSL2" under "Login and authentication"

Current Documentation

The troubleshooting page currently says:

Browser-based login in WSL2 can fail in two ways: WSL can't open your Windows browser, or the terminal won't accept the pasted authorization code. If the browser opens but pasting the code back into the terminal does nothing, your terminal's paste binding likely isn't reaching the prompt. Try your terminal's alternate paste shortcut, often right-click or Shift+Insert in Windows Terminal, or run login outside the interactive UI: ``bash theme={null} claude auth login `` This fallback also applies on native Windows or any terminal where pasting the code into the interactive prompt fails.

What's Wrong or Missing?

Claude Code v2.1.126 added a more specific fallback: claude auth login can accept the OAuth code pasted into the terminal when the browser callback cannot reach localhost, such as in WSL2, SSH sessions, and containers.

The current troubleshooting section still frames claude auth login mainly as a workaround for terminal paste binding failures in the interactive UI. It does not tell users what to do when the browser login succeeds but the redirect/callback to localhost cannot complete, which is the exact remote/container scenario addressed by the v2.1.126 change.

The nearby authentication page does mention the generic prompt:

If your browser shows a login code instead of redirecting back after you sign in, paste it into the terminal at the Paste code here if prompted prompt.

But the troubleshooting page for WSL2 and related remote login failures does not connect that behavior to claude auth login or to localhost callback failures.

Suggested Improvement

Update the WSL2 troubleshooting section to include the v2.1.126 behavior. For example, after the claude auth login command, add:

If the browser completes sign-in but cannot redirect back to Claude Code because the localhost callback is unreachable, copy the OAuth code shown in the browser and paste it into the terminal when claude auth login prompts for it. This works in WSL2, SSH sessions, containers, and other environments where the browser and Claude Code process cannot communicate over localhost.

Optionally rename the section or add a short subsection so it covers "WSL2, SSH, and containers" rather than only WSL2.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/troubleshoot-install | 738-759 | WSL2 OAuth troubleshooting recommends claude auth login but does not mention pasted OAuth codes for unreachable localhost callbacks |
| https://code.claude.com/docs/en/authentication | 13-17 | General login docs mention pasting a browser code into the terminal, but not the claude auth login remote/container fallback |

Version context: Claude Code v2.1.126 added support for claude auth login accepting the OAuth code pasted into the terminal when the browser callback cannot reach localhost.