Troubleshooting

codex: command not found after installing

npm finished installing, but your current terminal hasn't reloaded PATH. Open a new terminal and try again.

If it still fails, check that npm's global bin directory is on your PATH:

npm config get prefix
# that directory + /bin must be on $PATH

EACCES: permission denied during npm install

Node was installed with system permissions (common on Linux). Two fixes:

Option 1 — change the npm prefix (quick):

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # add this line to ~/.bashrc or ~/.zshrc

Option 2 — use nvm (recommended long-term):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts

Then re-run the install command.

Wrong or expired key (401 / unauthorized)

• Check the key in ~/.codex/auth.json is correct and complete (keys start with sk-)
• To switch keys, re-run the install command with the new key — the old config is backed up automatically

Windows: config file has an encoding problem

If you edited the file by hand in PowerShell using Set-Content -Encoding UTF8, PowerShell 5.1 prepends a BOM that breaks Codex's TOML/JSON parsing. Fix: use the install script (writes clean BOM-less files), or save the file in VS Code with UTF-8 encoding (not UTF-8 with BOM).

Restoring an old config

Every script run backs up the previous config next to the new file:

ls ~/.codex/*.bak.*
# restore by copying back, e.g.
cp ~/.codex/config.toml.bak.20260811120000 ~/.codex/config.toml

Still stuck?

Contact support with a screenshot of the error — see the channels on Getting started.