Lesson 490 of 2116
When Codex Fails: Debugging The Agent
Codex tasks fail in characteristic ways. Recognizing the failure mode is faster than retrying with a slightly different prompt.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1Failures have shapes
- 2agent failure modes
- 3context exhaustion
- 4tool loop
Concept cluster
Terms to connect while reading
Section 1
Failures have shapes
Codex tasks rarely fail with 'I cannot do this'. They fail in subtler ways: huge sprawling diffs, looped tool calls, plausible-but-wrong code. Each failure mode has a fix. Recognizing the shape gets you there faster than retrying with vibes.
Six common failure modes
Compare the options
| Symptom | Failure mode | Fix |
|---|---|---|
| Diff is enormous | Scope drift | Add diff cap to brief |
| Same tool called repeatedly | Tool loop | Inspect the tool's output — likely empty |
| Tests still fail at end | Stuck in 'almost there' loop | Cap retries; surface the failure |
| Plausible code that doesn't compile | Hallucinated API | Add the actual API surface to context |
| Edits to off-limits files | Boundary missed in brief | Reinforce off-limits in AGENTS.md |
| Outputs the right code, wrong place | Wrong project structure | Add a 'project layout' section to AGENTS.md |
When to retry vs when to redesign
- 1Retry with a tighter brief if the task was good but the brief was loose
- 2Redesign the brief if the agent visibly misunderstood the goal
- 3Switch agents if the same task fails on Codex but works elsewhere
- 4Hand it to a human if the task itself is ambiguous
- 5Abandon the task if the cost of clarification exceeds the cost of doing it yourself
Applied exercise
- 1Find your last three failed Codex tasks
- 2For each, pick which row of the failure-mode table matches
- 3Apply the listed fix and retry once
- 4If two of three now pass, you have a debugging method that works for your repo
Key terms in this lesson
The big idea: agent failures repeat. Catalog yours and your fix rate climbs without changing the model.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “When Codex Fails: Debugging The Agent”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 45 min
Structured Outputs: Make the Model Return Data You Can Trust
For production apps, pretty prose is often the wrong output. Learn when to use structured outputs, function calling, and schema validation.
Creators · 9 min
Pro Search vs Default: When To Spend The Compute
Pro Search runs more queries, reads more pages, and routes to a stronger model. It is not always worth the wait — knowing when it is is the skill.
Creators · 10 min
Perplexity API: Building RAG Without Owning The Pipeline
The Perplexity API gives you cited search answers with one call. It is the cheapest way to add grounded retrieval to a product — and the limits are worth understanding.