Systematic Debugging Across Surfaces

It is 3 AM and your pager fires. The payments service is returning 500 errors. The error log shows a stack trace pointing to a dependency you upgraded yesterday. You need to diagnose the issue, identify the root cause, and ship a fix — all before customers wake up. This is where Codex’s multi-surface architecture turns a stressful incident into a methodical debugging session.

What You’ll Walk Away With

• A structured debugging workflow that works across all Codex surfaces
• Surface-specific debugging techniques: App for visual diff review, CLI for scriptable diagnosis, Cloud for isolated reproduction, IDE for real-time editing
• Copy-paste prompts for the most common debugging scenarios
• Strategies for debugging race conditions, intermittent failures, and production-only bugs

The Debugging Framework

1. Reproduce: Confirm the bug exists and identify the minimal reproduction steps.
2. Isolate: Narrow down which component, module, or change introduced the bug.
3. Diagnose: Find the root cause in the code.
4. Fix: Implement the minimal change that resolves the issue.
5. Verify: Run the test suite, add a regression test, and confirm the fix.

Surface-Specific Debugging

CLI

Best for: Quick diagnosis, scriptable debugging, and CI failures.

# Diagnose a test failure
codex exec --full-auto \
  "Run npm test, capture the output, identify why the payments test
   is failing, find the root cause in the source code, and fix it.
   Run the test again to verify."

# Analyze a production error
codex "Here is a production stack trace from our payments service:
[paste stack trace]
Find the root cause in the codebase. The service was working until
we upgraded stripe-node from 14.x to 15.x yesterday."

App

Best for: Visual diff review, parallel investigation threads, and worktree isolation.

Open a Worktree thread so your debugging does not affect your current work:

1. Select “Worktree” mode, base it on your production branch
2. Drop a screenshot or paste the error message into the composer
3. Let Codex investigate while you continue other work
4. Review the diff in the App’s visual diff pane
5. Sync the fix to your local checkout when satisfied

Cloud

Best for: Reproducing environment-specific issues, heavy analysis, and best-of-N diagnosis.

# Submit a cloud debugging task
codex cloud exec --env production-mirror \
  "The /api/payments endpoint returns 500 with the error
   'TypeError: Cannot read property of undefined'. Reproduce
   the issue, find the root cause, implement a fix, and add
   a regression test."

Prompt: Diagnose a race condition

“I have an intermittent test failure in tests/services/order.test.ts. The test ‘should process concurrent orders’ fails about 30% of the time with ‘Expected 2 but received 1’. This suggests a race condition. Analyze the OrderService in src/services/order.ts, identify the race condition, implement a fix using proper synchronization, and run the test 50 times to verify the fix is stable.”

Common Debugging Scenarios

CI Failure After Dependency Upgrade

Our CI started failing after upgrading typescript from 5.3 to 5.5.
The errors are in src/types/. Read the TypeScript 5.5 migration guide
and fix the type errors. Do not downgrade TypeScript. Run the type
checker after each change.

Production Error with Stack Trace

Here is a production error from Sentry:
[paste full error with stack trace]

Find the exact code path that leads to this error. The error started
appearing after commit abc1234. Use git diff abc1234~1..abc1234 to
identify what changed. Implement a fix and add a regression test.

Memory Leak Investigation

Our Node.js service's heap grows by 50MB/hour under load. The leak
was introduced sometime in the last 2 weeks. Analyze recent commits
to src/services/ for common leak patterns: event listeners not removed,
closures capturing large objects, growing arrays or maps without eviction.
Identify the likely cause and propose a fix.

Prompt: Bisect a regression

“The ‘user search’ feature stopped returning results after a recent change. Use git log to find commits from the last 5 days that touched src/services/search.ts or src/routes/search.ts. For each suspect commit, analyze whether it could cause the regression. Identify the breaking commit and fix the issue.”

Image-Based Debugging

The Codex App and CLI support image input. For UI bugs, drop a screenshot into the composer:

# CLI with screenshot
codex -i screenshot-broken-layout.png \
  "This screenshot shows a broken layout in the dashboard header.
   The navigation items should be horizontally aligned but they
   are stacking vertically. Find the CSS issue and fix it."

In the App, hold Shift while dropping an image to add it as context.

When This Breaks

• Agent cannot reproduce the bug: The bug may depend on environment state (database, cache, external service). Provide as much context as possible: error messages, stack traces, recent changes, and environment details.
• Fix works but introduces a regression: The agent focused too narrowly. Ask it to run the full test suite, not just the failing test.
• Intermittent bug disappears during debugging: Add explicit logging or assertions. Ask Codex to add temporary debug instrumentation that captures the state when the error would occur.
• Agent blames the wrong commit: Provide the exact timeframe when the bug appeared and the git log. Ask the agent to analyze each suspect commit individually.

What’s Next

• Review Strategies — Review debugging fixes with appropriate rigor
• Context Patterns — Keep debugging context sharp across long investigation sessions
• Prompt Engineering — Write better debugging prompts