Skip to content

troubleshooting.md

Latest commit

 

History

History
148 lines (106 loc) · 4.91 KB

troubleshooting.md

File metadata and controls

148 lines (106 loc) · 4.91 KB

Troubleshooting

Recovery guide for install, login, switching, worktree storage, and stale local auth state.

Start Here

codex auth doctor --fix
codex auth check
codex auth forecast --live

If the account pool is still not usable:

codex auth login

Verify Install And Routing

Check which codex executable is running:

where codex
codex --version
codex-multi-auth --version
codex auth status
codex multi auth status
npm ls -g codex-multi-auth

If an old scoped package is still active:

npm uninstall -g @ndycode/codex-multi-auth
npm i -g codex-multi-auth

codex multi auth status is a compatibility alias. The canonical command family remains codex auth ....

Browser And OAuth Problems

Symptom Likely cause Action
Browser opens unexpectedly Normal browser-first OAuth flow Complete the auth step and return to the terminal
OAuth callback port 1455 is in use Another local process owns the port Stop the conflicting process and rerun codex auth login
Browser or callback handoff is unavailable Remote, SSH, container, or headless shell Run codex auth login --device-auth; use codex auth login --manual only if device auth is unavailable
missing field id_token Stale or malformed auth payload Re-login the affected account
refresh_token_reused The token pair rotated in another context Re-login the affected account
token_expired The refresh token is no longer valid Re-login the affected account

Switching And State Problems

Symptom Likely cause Action
Switch succeeds but the wrong account stays active Stale Codex CLI sync state Re-run codex auth switch <index> and restart the session
All accounts look unhealthy The entire pool is stale or damaged Run codex auth doctor --fix, then add at least one fresh account
The dashboard shows old account state Local files were updated outside the current session Run codex auth list, then codex auth check

Runtime Rotation Problems

Symptom Likely cause Action
codex auth rotation status says disabled Stored setting or env override is off Run codex auth rotation enable, remove CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=0, or set CODEX_MULTI_AUTH_RUNTIME_ROTATION_PROXY=1 for one process
Forwarded Codex session does not show the local provider Command is help/non-requesting, rotation is disabled, or the official CLI was not launched through the wrapper Check where codex, then run codex auth rotation status
Pool exhausted error from the proxy Every managed account is unavailable for that model/family Run codex auth rotation status, then codex auth forecast --live
Packaged app still uses normal Codex routing App bind was not installed or was removed Run codex auth rotation bind-app, then reopen the app
App bind needs to be removed You want the official app config restored Run codex auth rotation unbind-app or codex auth rotation disable

The runtime proxy is loopback-only and default-on. It routes Responses traffic only for forwarded request-bearing official Codex sessions and supported app launches.

Worktrees And Project Storage

Symptom Likely cause Action
A worktree asks for login again The worktree still points at a legacy path key Run codex auth list once in the worktree to trigger migration into repo-shared storage
A repo should not share accounts with another repo Project-scoped storage is not enabled or not in use Review the project storage rules in reference/storage-paths.md

Diagnostics Pack

codex auth list
codex auth status
codex auth check
codex auth verify-flagged --json
codex auth forecast --live
codex auth fix --dry-run
codex auth report --live --json
codex auth doctor --json

Soft Reset

PowerShell:

Remove-Item "$HOME\.codex\multi-auth\openai-codex-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\openai-codex-flagged-accounts.json" -Force -ErrorAction SilentlyContinue
Remove-Item "$HOME\.codex\multi-auth\settings.json" -Force -ErrorAction SilentlyContinue
codex auth login

Bash:

rm -f ~/.codex/multi-auth/openai-codex-accounts.json
rm -f ~/.codex/multi-auth/openai-codex-flagged-accounts.json
rm -f ~/.codex/multi-auth/settings.json
codex auth login

Issue Report Checklist

Attach these outputs when opening a bug report:

  • codex auth report --json
  • codex auth doctor --json
  • codex --version
  • codex-multi-auth --version
  • npm ls -g codex-multi-auth
  • the failing command and full terminal output

Related