Debugging and troubleshooting runs

Verbose and debug logging, session logs, common install and authentication failures, sandbox denials, and diagnosing a loop that stops making progress.

Getting visibility

# ask for the reasoning and the tool calls to be shown
codex --help | grep -i -E "verbose|debug|log"     # confirm the flags for your version

codex -c hide_agent_reasoning=false "explain why the test at line 40 fails, \
  showing the commands you ran and their output"

# capture a run for later inspection
codex exec --json "run the test suite and report failures" 2>&1 | tee run.jsonl

# where session and log files live for the version you have
ls -la ~/.codex 2>/dev/null
ls -la ~/.codex/log 2>/dev/null | tail -20

Reproduce the failure in a non-interactive run first. A recorded transcript you can reread is worth more than a scrollback you are trying to remember.
Check the tool version at the start of any debugging session. Behaviour and configuration keys change, and a fix from a blog post may no longer apply.
Log the exact command, the working directory and the task text. Most "the agent did something strange" reports turn out to be a different directory or a stale task description.

The failures you will actually hit

Symptom	Likely cause	Check
Command not found after install	Global npm bin directory not on PATH	`npm bin -g` and your shell profile
Authentication error on every run	Expired session or missing API key	Re-authenticate, or confirm the environment variable
`sandbox denied` on a write	Path outside the workspace	Add the path to `writable_roots` or work inside the repo
Network request blocked	`network_access = false`	Install dependencies outside the run
The run stops immediately	A failing pre-flight check or a bad config key	Run with the base config only, then add settings back
It edits the same file repeatedly	The task conflicts with a rule or a failing gate	Read the transcript, then narrow or restate the task
Everything is slow	High reasoning effort on a wide context	Lower the effort, narrow the scope, split the task
Output truncated in the terminal	A large diff or a large tool result	Use `--json` and read the file

# isolate a configuration problem by starting from nothing
mv ~/.codex/config.toml ~/.codex/config.toml.bak
codex --version && codex exec "print the working directory and stop"

# add settings back one block at a time until the failure returns
cp ~/.codex/config.toml.bak ~/.codex/config.toml

# prove the sandbox is the cause, not the task
codex --sandbox workspace-write "create a file named sandbox-probe.txt in the repo root"
git status --short

# and prove whether a path outside the workspace is the blocker
codex --sandbox workspace-write "write to /tmp/sandbox-probe.txt and report the error verbatim"

Bisect the configuration. A large config file with one bad key produces a symptom far from the cause, and comment-out halves is faster than reasoning about it.
Read the error verbatim rather than the agent's paraphrase of it. The paraphrase is often a guess, and the raw message names the actual path or rule.
Reproduce outside the agent: run the failing command in your own shell. If it fails there too, the problem was never the agent.

When a run stops making progress

The signature is repetition: the same file edited, the same test run, the same error. Read the transcript for the loop point and interrupt rather than waiting.
The most common cause is a gate that cannot pass: a test the agent is forbidden to change, a linter it cannot satisfy, or a missing dependency it cannot install with the network off.
The second most common cause is an ambiguous requirement. The agent tries one interpretation, fails a check, tries the other, fails again, and oscillates.
Break the loop by removing one constraint at a time and observing which one releases it. Then decide whether the constraint or the task should change.

# a bounded loop: interrupt on a time budget rather than watching it forever
timeout 600 codex exec --sandbox workspace-write --ask-for-approval never \
  "make tests/test_export.py pass without modifying that file" || echo "run timed out"

# capture the state so the next attempt starts from information, not scratch
git diff > attempt-1.patch
git status --short > attempt-1-status.txt
git restore . && git clean -fd

# a third attempt should change the conditions, not repeat the prompt
#   - add the missing dependency outside the run
#   - write the test yourself and ask only for the implementation
#   - split the task into two smaller ones

💡

A run that fails twice under identical conditions will usually fail a third time. Change something real between attempts: the environment, the constraint, or the size of the task. Repeating the prompt with stronger wording is not a change.

FAQ

Where do I find session logs?

In the Codex home directory, typically under ~/.codex/log, with session state alongside it. The exact layout changes between versions, so list the directory rather than assuming a path.

It says the sandbox denied a write. What now?

Confirm the path is genuinely needed. If it is, add it explicitly to writable_roots for that task only, and do not widen the whole sandbox because one build tool insisted on writing to a cache directory.

Approval modes and sandboxing Configuration with config.toml and profiles

Last refreshed 2026-09-18.

Debugging and troubleshooting runs

Getting visibility

The failures you will actually hit

When a run stops making progress

FAQ

Related