Codex CLI Logs: Run doctor, Then Find TUI or SQLite Logs¶

Audience: diagnose a Codex failure with doctor and local logs

codex doctor --summary
codex doctor --json > codex-doctor.json

Use doctor to identify the running Codex binary, loaded config, auth status, network path, and actual log/state locations. Do not assume that ~/.codex/log/codex-tui.log exists on every installation.

Key Points¶

Run codex doctor before searching individual log files
Treat TUI logs, SQLite logs, and session JSONL as different data sources
Share a redacted summary in public issues instead of raw local files

Which diagnostic source should you use?¶

Codex has four different kinds of local diagnostic data.

Source	First access method	What it shows	Public-sharing risk
Health report	`codex doctor --summary`	Install, config, auth, network, and state categories	Full JSON can contain local paths
TUI text log	Log directory reported by doctor	Recent warnings and errors	Can include prompts and commands
SQLite log DB	Log DB reported by doctor	Structured internal logs	Do not upload the raw DB
Session JSONL	`$CODEX_HOME/sessions/`	Conversations, tool calls, and results	Usually contains private code and paths

auth.json is not a diagnostic log. It is authentication material and can contain tokens. Never print, copy, or attach its contents.

Step 1: Use doctor to identify the failing layer¶

Read the summary first¶

codex doctor --summary

Start with categories, not individual log lines:

installation / runtime: PATH duplicates, current executable, update path
config: effective CODEX_HOME and config.toml
auth: whether authentication is configured, without exposing tokens
network / websocket: HTTP reachability and WebSocket handshake
sandbox: approval, file, and network boundaries
state: state DB, log DB, and rollout-file integrity
MCP: static configuration problems

For example, if HTTP reachability succeeds but the WebSocket handshake fails, investigate VPN, IPv6, proxy, and the WebSocket route before deleting authentication state.

Save JSON, then extract only what matters¶

codex doctor --json > codex-doctor.json

Older CLI builds may not support --json. If the option fails, record codex --version and check the available update path first.

Machine-readable does not mean fully anonymous. Official issue reports often share a redacted summary instead of raw JSON because the report can include local usernames, paths, project names, and state locations.¹

Step 2: Read the actual log paths from doctor¶

Codex logging varies by install path and feature set. An environment can have either or both of these:

$CODEX_HOME/log/codex-tui.log
<sqlite home>/logs_2.sqlite

In codex doctor --json, look under config.load and state.paths for log dir, log DB, and sqlite home. A missing text-log directory does not mean there are no logs when logs_2.sqlite is healthy.

Only when the text log exists, inspect a narrow tail and exact patterns:

tail -n 120 "$CODEX_HOME/log/codex-tui.log"
rg -n -i 'error|warn|reconnect|401|403|timeout|mcp' \
  "$CODEX_HOME/log/codex-tui.log" | tail -n 80

If CODEX_HOME is unset, replace the path with the one reported by doctor.

The SQLite log schema can change. Do not bake ad hoc SQL queries into permanent support steps. Start with doctor's DB-integrity result and the exact user-visible error. Never upload the raw database to a public issue.

Step 3: Route by exact error text¶

Doctor or UI signal	Next branch
HTTP `401` or auth failed	Login state, account, and system clock; do not inspect token contents
WebSocket handshake failed	VPN, proxy, IPv4/IPv6, and reconnect troubleshooting
`Network access is restricted`	Workspace-sandbox network setting
`missing field sandboxPolicy`	Browser / Computer Use and `node_repl` version compatibility
MCP command/env/cwd warning	Executable, environment variables, and cwd for that MCP server
`failed to initialize sqlite state runtime`	DB error code and Windows/WSL path boundary
Multiple Codex binaries on PATH	Mismatch between the running binary and update target

Do not match an error to an invented sample log. Start with the exact one-line message and verify that doctor points to the same layer.

Minimal public issue template¶

This is usually enough for maintainers to begin triage:

## Environment
- Codex version: `<codex --version>`
- Surface: CLI / Desktop / IDE extension
- OS: `<OS and version>`
- Install method: npm / Homebrew / standalone / Store

## Exact error
`<one exact error message>`

## Reproduction
1. ...
2. ...
3. ...

## Doctor summary (redacted)
- installation: ...
- config: ...
- auth: configured / not configured
- network HTTP: ...
- WebSocket: ...
- state DB: ...

## Already tried
- ...

Never attach these publicly¶

auth.json, API keys, cookies, or authorization headers
The raw logs_2.sqlite database
Raw session JSONL files
A zip of .codex or the entire CODEX_HOME
.env, SSH keys, or cloud credentials
An unreviewed full TUI log

Official Codex issue reports warn that SQLite logs and session files can contain prompts, local paths, command history, project names, and tool output.²

Common misdiagnoses¶

Doctor passed, so Desktop must be healthy¶

The terminal CLI and Desktop's embedded app-server may be different binaries. Record the About build for a desktop-only failure.

No codex-tui.log means no logs exist¶

Structured logs may live in logs_2.sqlite. Check state.paths in doctor.

A 401 means auth.json should be deleted¶

Deleting auth state is a mutation with recovery cost. Check login status, doctor's auth category, system time, and the exact HTTP error first.

`/feedback` always returns fixed fields¶

Slash commands and their output evolve. Do not build a troubleshooting guide around fictional request IDs or a fixed output schema that the installed CLI may not provide.

Summary¶

Start with codex doctor --summary; share only the necessary redacted parts of --json
Discover log dir and log DB from doctor instead of assuming a fixed path
Treat TUI logs, SQLite DBs, session JSONL, and auth files as different sensitivity classes
Share one exact error plus a doctor summary, not raw logs or databases