Codex CLI Logs: Location, Debug Flags & 401 Error Fix (2026)¶
When encountering connection errors or "Re-connecting" loops in Codex CLI, mastering accurate diagnostic log reading enables rapid problem identification and effective issue reporting. This article provides practical guidance on analyzing the /feedback command and log files in detail.
This is a follow-up to the morning article
Morning article: Codex CLI "Re-connecting" Loop Complete Solution
Goals¶
- Understand the structure of Codex CLI diagnostic log files and important log patterns
- Master how to read information obtained from the
/feedbackcommand - Identify log signatures for different failure patterns and determine root causes
Overview of Diagnostic Information¶
There are three diagnostic information sources used for Codex CLI troubleshooting:
| Source | Acquisition Method | Primary Use |
|---|---|---|
/feedback command | Execute within Codex session | Obtain Request ID and connection state snapshot |
codex-tui.log | ~/.codex/log/codex-tui.log | Detailed event logs and error stack traces |
auth.json | ~/.codex/auth.json | Check authentication state (token expiration, etc.) |
/feedback Command Details¶
Execution Method and Output¶
# Execute within Codex session
/feedback
Output information:
Request ID: req_abc123xyz...
Session ID: ses_def456uvw...
Connection status: connected
Last error: null
Uptime: 00:23:45
Active tools: 12
MCP servers: 2 connected
Reading Critical Fields¶
| Field | Meaning | Troubleshooting Checkpoint |
|---|---|---|
Request ID | Last API call identifier | Essential for Issue reporting. Enables OpenAI support to locate server-side logs |
Connection status | Current connection state | reconnecting/disconnected indicates abnormal state |
Last error | Most recent error content | 401 Unauthorized indicates auth issues, 503 suggests server load |
MCP servers | Number of connected MCP servers | Check MCP config if different from expected value |
Practical Log File Analysis¶
Log File Location and Structure¶
Codex CLI's main log is stored at:
~/.codex/log/codex-tui.log
Log format (example):
2025-10-27T12:34:56.789Z [INFO] Session started: ses_abc123
2025-10-27T12:35:01.234Z [DEBUG] MCP server 'filesystem' connected
2025-10-27T12:35:15.678Z [ERROR] WebSocket reconnection failed: timeout after 30s
2025-10-27T12:35:16.123Z [WARN] Falling back to polling mode
Log Level Priority¶
| Level | Meaning | Response Priority |
|---|---|---|
ERROR | Processing failure / connection error | Highest (immediate action required) |
WARN | Abnormal behavior / fallback | High (investigation recommended) |
INFO | Normal operation milestones | Low (context confirmation) |
DEBUG | Detailed internal processing | Low (developer-oriented) |
Log Signatures by Failure Pattern¶
Pattern 1: Authentication Error¶
[ERROR] Authentication failed: 401 Unauthorized
[DEBUG] Token refresh attempt 1/3
[ERROR] Token refresh failed: invalid_grant
Cause: Corrupted auth.json or expired token
Solution: Execute Method 2 from morning article
Pattern 2: MCP Connection Failure¶
[INFO] Starting MCP server 'custom-tool'
[ERROR] MCP handshake timeout after 10s
[WARN] MCP server 'custom-tool' disabled
Cause: MCP server startup failure or network issues
Solution: Disable the problematic server in ~/.codex/config.toml
# Comment out problematic MCP server
# [mcp_servers.custom-tool]
# command = "..."
Pattern 3: WebSocket Disconnection Loop¶
[INFO] WebSocket connected
[ERROR] WebSocket closed: code=1006 (abnormal closure)
[INFO] Reconnecting... (attempt 1/∞)
[ERROR] WebSocket closed: code=1006 (abnormal closure)
[INFO] Reconnecting... (attempt 2/∞)
Cause: Network instability or proxy/VPN interference
Solution: 1. Stop with Ctrl+C 2. Wait 60 seconds, then restart single instance (Method 1 from morning article)
Pattern 4: VS Code Extension Interference¶
[WARN] Conflicting extension detected: vscode-codex
[ERROR] Network access blocked by extension policy
[INFO] Falling back to CLI-only mode
Cause: VS Code extension blocking network access
Solution: Disable VS Code extension and run CLI standalone
Practical Log Analysis Workflow¶
Step 1: Identify Error Timestamp¶
# Extract ERROR logs from last 30 minutes
grep "ERROR" ~/.codex/log/codex-tui.log | tail -n 20
Step 2: Check Surrounding Context¶
# Display 10 lines before/after error (filter by timestamp)
grep -A 5 -B 5 "12:35:15" ~/.codex/log/codex-tui.log
Step 3: Pattern Matching¶
Cross-reference error messages with "Log Signatures by Failure Pattern" above to identify the root cause.
Step 4: Obtain Request ID via /feedback¶
Execute /feedback within the Codex session and record the Request ID. Attach this when reporting issues.
Best Practices for GitHub Issue Reporting¶
Effective Issue Report Structure¶
## Environment
- Codex CLI Version: 0.50.0
- OS: Ubuntu 22.04 / WSL2
- Node.js: v20.10.0
## Reproduction Steps
1. Launch `codex`
2. Request "large-scale code changes"
3. After 3 steps, enters Re-connecting loop
## Frequency
- 2-3 times per day (when running multiple parallel sessions)
## Diagnostic Information
- Request ID: req_abc123xyz...
- Session ID: ses_def456uvw...
- Log excerpt:
```
[ERROR] WebSocket closed: code=1006
[INFO] Reconnecting... (attempt 15/∞)
```
## Attempted Workarounds
- [x] Full stop → 60s → restart → Temporarily recovered
- [x] Authentication refresh → No effect
- [ ] MCP isolation → Not attempted
Reporting Patterns to Avoid¶
| ❌ Avoid | ⭕ Recommended |
|---|---|
| "It doesn't work" | Specific error messages and log excerpts |
| No version info | Attach codex --version output |
| Vague reproduction steps | Step-by-step reproduction procedure |
| Paste entire log file | Extract only relevant portions (within 20 lines) |
Automated Log Monitoring Script¶
For continuous log monitoring, use this script:
#!/bin/bash
# codex-log-monitor.sh - Notify on ERROR occurrence
LOG_FILE="$HOME/.codex/log/codex-tui.log"
tail -f "$LOG_FILE" | grep --line-buffered "ERROR" | while read line; do
echo "🚨 Error detected: $line"
# Send notification on macOS
# osascript -e "display notification \"$line\" with title \"Codex Error\""
done
Execution:
chmod +x codex-log-monitor.sh
./codex-log-monitor.sh &
Summary¶
Accurately interpreting Codex CLI diagnostic logs yields the following benefits:
- Reduce troubleshooting time by an average of 50%
- Improve GitHub Issue report quality, accelerating development team fixes
- Enable preventive measures through understanding failure patterns