Troubleshooting
Quick fixes for the most common CodexUse issues. Find your symptom in the left column and apply the fix on the right.
| Issue | Fix |
|---|---|
| Can’t sign in / sign-in loop | Retry sign-in in your browser. If headless, use device auth. Check system clock skew. |
codexuse not found | In CodexUse Settings, click Add codexuse to Terminal, then open a new terminal. Without the app, run npm install -g codexuse-cli on Node.js 22.13 or later. |
codexuse says it needs Node.js 22.13 | The npm copy needs Node.js 22.13 or later. Update Node, or use the copy the app adds with Add codexuse to Terminal, which needs no Node.js. |
codexuse --version shows (npm) after you added the app's copy | An older npm install runs first. Run npm uninstall -g codexuse-cli, then open a new terminal. |
| Codex defaults shows a syntax error | Fix the line it names in ~/.codex/config.toml. Until then every account keeps its current Codex settings. |
brew upgrade --cask codexuse fails with App source '/Applications/CodexUse.app' is not there or It seems there is already an App at '/opt/homebrew/Caskroom/.../CodexUse.app' | Homebrew's app bundle or symlink is out of sync, often after stale cask metadata or an in-app update touched the Homebrew-managed copy. Run brew uninstall --cask --force hweihwang/codexuse/codexuse, remove any dangling /Applications/CodexUse.app, then brew install --cask hweihwang/codexuse/codexuse. |
| Rate limit data missing | Codex CLI must be installed and reachable. Use --no-usage if you only need the account list. |
| Duplicate account warning | If two accounts resolve to the same underlying OpenAI identity, they will share the same rate-limit headroom. Being in the same ChatGPT Business workspace alone does not create separate limits. |
| MCP server fails to start | Check the server block in that account’s config.toml and run the command manually to confirm. |
| Auto-roll not rolling | Auto-roll triggers when remaining usage reaches the configured % left threshold. |