Troubleshooting & Diagnostics

When Codex breaks, the instinct is to start changing things — reinstall, flip a flag, paste the error into a search box. Resist it. Codex is a local Rust CLI with a small, knowable state directory, which means almost every failure is localizable before you touch anything.

Fix one habit and most sessions get shorter: codex doctor first, logs second, targeted fix third.

• codex doctor tells you which layer is broken — install, config, auth, runtime, Git, terminal, app-server, or threads — without you having to reproduce the failure by hand.
• The ~/.codex directory (overridable via CODEX_HOME) holds everything stateful: your config, credentials, sessions, and logs. If you know what lives there, you know what to inspect and what to reset.
• RUST_LOG turns up the verbosity when the report isn't enough, so you see the actual request, sandbox call, or error that failed.

The rest of this lesson is that reflex made concrete: the diagnostic command, the state map, the two or three failure classes you'll actually hit (sandbox, auth, TLS, monorepo), and the cheap recovery moves that beat a reinstall almost every time.

codex doctor generates a local diagnostic report — the single best first move when an install is broken or before you file a support issue. It checks the health of every layer Codex depends on:

• Installation — binary, version, install path
• Configuration — config.toml parsing and layering
• Authentication — credential state and login method
• Runtime — the sandbox/runtime environment
• Git — repo detection and Git availability
• Terminal — TUI capabilities
• App-server — the local app-server process
• Threads — your session/thread inventory

codex doctor              # human-readable report
codex doctor --summary    # condensed view
codex doctor --all        # run every check, including slower ones
codex doctor --json       # redacted, machine-readable report
codex doctor --no-color   # plain output (logs, CI)
codex doctor --ascii      # ASCII-only output

The --json form writes a redacted codex-doctor-report.json — safe to share because it strips secrets. That same report is what gets attached when you run /feedback to send logs to the maintainers, so codex doctor --json + /feedback is the standard 'I'm stuck, here's the evidence' escalation path.

Read the report top-down and stop at the first failing layer — a broken auth check below a broken install check is usually just a symptom of the install problem.

Almost everything Codex persists lives under CODEX_HOME (default ~/.codex). Knowing this map turns 'something is wrong' into 'inspect this file':

If you've relocated state with CODEX_HOME, substitute that path everywhere above. The macOS Desktop app logs separately, under:

~/Library/Logs/com.openai.codex/YYYY/MM/DD

When you suspect a layer, go straight to its file: a config that won't parse → config.toml; an auth loop → auth.json (and re-login); a TUI that froze mid-task → ~/.codex/log/codex-tui.log.

A few related env vars are worth knowing because they move this state around: CODEX_HOME relocates the whole directory, and CODEX_SQLITE_HOME points at the SQLite state path. Relocating CODEX_HOME is itself a clean troubleshooting move — point it at a fresh directory to test with a clean slate without destroying your real config.

When the doctor report and the obvious files aren't enough, raise verbosity. Codex is a Rust program, so it honors the standard RUST_LOG environment variable, and the extra output lands under CODEX_HOME.

# Coarse global level
RUST_LOG=debug codex

# Levels, low to high: error | warn | info | debug | trace
RUST_LOG=trace codex

# Targeted filters — much less noise than global trace
RUST_LOG=codex_core=debug,codex_tui=debug codex

Prefer targeted filters (codex_core=debug,codex_tui=debug) over a blanket RUST_LOG=trace. Global trace produces a firehose; scoping to the crates you suspect (core agent logic vs. the terminal UI) keeps the log readable and points you at the real failure faster.

Workflow: set RUST_LOG, reproduce the failure once, then read ~/.codex/log/codex-tui.log (or the level you raised) for the line where it actually broke — a failed request, a sandbox call that was refused, an MCP server that timed out.

On Linux and WSL2, the most common error you'll meet is 'couldn't set up sandbox'. Codex enforces its filesystem/network boundary at the OS level, and when the OS can't provide that enforcement, Codex refuses to run rather than run unsandboxed. That refusal is a feature — but it surprises people.

The enforcement mechanism differs by platform:

On Linux/WSL2, the cause is almost always one of two things: bubblewrap isn't installed, or unprivileged user namespaces are disabled/restricted by the kernel or a hardened host. Fixes, in order:

# 1) Install bubblewrap (Debian/Ubuntu)
sudo apt-get install -y bubblewrap
bwrap --version            # confirm it's on PATH

# 2) Make sure unprivileged user namespaces are enabled (the exact
#    kernel knob/sysctl varies by distro and hardened-host policy —
#    check your distro's docs and the live sandboxing reference)

# 3) Confirm the runtime layer in the doctor report
codex doctor --summary     # look at the Runtime / sandbox check

If you're on a locked-down corporate host where namespaces can't be enabled, your options are to run inside WSL2 (on Windows) or a permitted container, or — only inside an already-hardened VM/container — to bypass the sandbox deliberately. macOS rarely needs any of this: Seatbelt ships with the OS, so a sandbox failure there usually points at a deeper install problem worth a codex doctor run.

Two classes of connection failure look similar but have different fixes: auth (Codex doesn't think you're logged in) and TLS (Codex can't trust the connection at all, usually behind a corporate proxy).

Auth recovery. Check state, then re-establish it:

codex login status         # exits 0 when logged in
codex login               # browser OAuth (default, recommended)
codex login --device-auth  # headless / no local browser
codex login --with-api-key # API-key sign-in (key via stdin)
codex logout               # clear stored creds, then login fresh

codex login status is scriptable — it exits 0 when you're logged in, non-zero otherwise — so it's the right check in CI or a pre-flight script. If login itself loops, the cleanest reset is codex logout followed by codex login, which rewrites ~/.codex/auth.json from scratch.

The corporate-TLS gotcha. On a corporate network that intercepts TLS (a 'man-in-the-middle' proxy with its own root CA), every Codex request can fail with certificate errors even though your login is fine. The fix is to point Codex at your organization's CA bundle:

# Tell Codex which CA bundle to trust (PEM file)
export CODEX_CA_CERTIFICATE=/path/to/corporate-ca.pem
# Or the standard OpenSSL variable, also honored:
export SSL_CERT_FILE=/path/to/corporate-ca.pem

If auth and certificates both look right but calls still fail, suspect the proxy's network rules next — and remember that in workspace-write, outbound network is OFF by default and must be opted into, which is a frequent 'why can't it reach the internet?' red herring.

Most of the time nothing is 'broken' — a turn went sideways, you cancelled, or Codex loaded the wrong config. These cheap moves fix the common cases without a reinstall:

• Recover a prompt after cancel. Pressed Ctrl+C and lost your carefully-typed prompt? Press Up to bring it back from draft history instead of retyping. (Ctrl+C cancels the turn; it does not silently eat your text.)
• Check pending approvals. If Codex looks 'stuck', it may simply be waiting on an approval. Look for the approval prompt before assuming a hang.
• Run git status. Because Codex works through your normal Git workflow and surfaces a transcript of every action, git status (and /diff) is your ground truth for what actually changed — and your rollback path is plain Git (there is no /undo).
• Start a focused new thread. A long, tangled session can drift. /new (fresh conversation, same session) or a new codex invocation with a tight prompt often outperforms fighting a confused thread. Session hygiene is troubleshooting.
• Open the right directory in a monorepo. Codex loads project config and AGENTS.md relative to where you launch it. If it's ignoring your settings, you're probably in the wrong subdirectory — open the directory that contains the .codex folder so the right config layer loads.