Common failure modes (and how to recover)

Claude Code is excellent. It is not infallible. Once you've used it for any length of time you'll see it confidently do the wrong thing, loop on a task, hallucinate an API that doesn't exist, or quietly drift away from what you asked. This isn't a sign the tool is broken — it's the nature of the technology. The skill is recognising failure within seconds and steering out of it.

Failure mode 1: the confident hallucination

Claude writes code that uses a function, a library, or an API call that simply doesn't exist. The code looks right. The names look plausible. It even compiles, sometimes. But when you actually run it, the import fails or the function isn't defined.

How to spot it:the function name is too perfect — it's exactly what you'd wish existed. No documentation references it. A quick web search turns up nothing.

How to recover:point at the suspect line and ask Claude to verify the function exists by reading the actual library docs or source. Often Claude will catch itself the moment it's asked to check. Then ask it to use a real equivalent.

Failure mode 2: the infinite loop

Claude is trying to fix a test failure. It changes the code. The test still fails. It changes it again. The test still fails — for a different reason now. It changes it again. And again. Each step makes a little sense; the trajectory doesn't.

How to spot it:the same file is being edited for the fourth or fifth time, and progress on the actual goal isn't visible. The test output keeps moving but never passes.

How to recover: stop the session. Ask Claude to step back and re-read the original requirement. The sequence of edits has usually drifted from what you actually wanted; resetting context fixes it. If the failure is a genuine puzzle, switch to plan mode and have Claude diagnose before further edits.

Failure mode 3: scope creep

You asked Claude to fix a one-line bug. It fixes it. It also renames three variables it didn't like, restructures a function it thought was poorly written, removes a comment it thought was outdated, and switches a library. The diff is twelve files.

How to spot it:the diff is much larger than the task warranted. Files you didn't mention got touched. Refactors appeared you didn't ask for.

How to recover:reject the diff. Re-prompt with explicit scope: "Touch only file X. Don't refactor anything. Don't rename anything. Just the one-line change." The scope drift is often a helpfulness reflex; bounding it explicitly cures it.

Failure mode 4: the lost-context drop-off

A long session has been going well. Then suddenly Claude seems to forget something important from earlier. It re-asks a question you already answered, or makes an assumption you previously corrected.

How to spot it: Claude is asking about something that was clearly established. The earlier context was probably compacted out as the conversation grew long.

How to recover:briefly restate the lost fact. Don't scold (it's not stubbornness, it's compaction). For facts that need to stick across the session, consider promoting them to CLAUDE.md — that survives compaction.

Failure mode 5: the silent wrong direction

Maybe the trickiest one. Claude doesn't loop, doesn't hallucinate, doesn't over-step — it just confidently builds something that isn't quite what you wanted. Each individual decision is reasonable; the cumulative result misses the mark.

How to spot it:at the end of a long task, the result "works" but feels off. The code is fine — it's the choice of approach, the architecture, the framing that's wrong.

How to recover: this is almost always a prompt problem, not a Claude problem. The original request underspecified what you wanted. Go back, write the request better — with examples, constraints, and counter-examples — and try again. Plan mode prevents most of these by surfacing the approach before the implementation.

Failure mode 6: tool-use thrashing

Claude opens file after file, greps over and over, exploring in widening circles, never quite committing to an action. You watch ten tool calls go by; nothing has been edited.

How to spot it:lots of read activity, little write activity, and Claude's next-step messaging gets vaguer instead of sharper.

How to recover:jump in and point at the right file directly. Often Claude is investigating because the original prompt didn't specify which part of the codebase to focus on. A nudge — "the answer is in src/billing/charge.ts" — turns thrashing into progress.

Failure mode 7: compounding misunderstanding

You said "rename X to Y." Claude renamed it everywhere — including in a comment that was historical context, including in a string used as a database key, including in a URL that's referenced externally. Each rename made local sense; the aggregate breaks the world.

How to spot it:shortly after a rename or refactor, things that shouldn't have been affected stop working.

How to recover: git is your friend. git diff shows every place the rename touched. git restore rolls back specific files where the change was wrong. Then ask Claude for a more surgical rename — only in code, not in strings, not in URLs.

The general recovery toolkit

Across all of these, the same handful of moves get used:

• Esc — interrupt the current tool run.
• Reject the diff— don't accept changes going the wrong way.
• git restore — roll back individual files.
• /clear — reset the conversation context without losing the project.
• Plan mode — slow down, make Claude write out the approach before more edits.
• Restart the session — sometimes the cleanest fix.

The mindset shift

New users react to Claude going wrong with frustration — "why can't it just do it right." Experienced users treat it like any other tool with a sharp edge: stay alert, course-correct fast, don't let a small drift become a big one. Most failure modes are recoverable in seconds if you catch them early. The skill is the catching.