When a step goes wrong
In a system built from separate parts, where Claude may be doing several things or handing work to other steps, failures are not rare events. They are a normal part of how it runs. What a step does when it cannot finish is a design decision, not something to leave to chance, and the two obvious answers, hide it or crash, are both wrong. The wider set of decisions this sits inside is Ways to run it for real.
Say it another way
Think of a cook who burns a sauce. Hiding it and sending the plate out anyway means a bad dish reaches the table with no one the wiser. Downing tools and stopping the whole kitchen punishes every other order for one mistake. The right move is to say what went wrong and what is to hand, the sauce is ruined but there is jus ready, so the head chef can choose what to send. A good system handles its own failures the same way.
Doing this with Claude Code
When you build a step that can fail, a subagent, a tool or a skill, decide its failure path on purpose.
Write the failure path into the prompt. Tell the step that if it cannot finish it should report what it was attempting, anything it managed to get and what to try instead, rather than crashing or going blank.
Keep what broke apart from what it found. An empty result and a failed lookup are different facts. Have the step say which one it is, so a timeout is never taken for a confirmed nothing.
Ask for the gaps to be marked. When results are combined into one answer, have it note which parts are well-supported and which are thin because something was missing, so a neat summary does not hide what never arrived.
Common questions
- Why is hiding a failure the wrong answer?
Swallowing a failure quietly and carrying on as though nothing happened lets a wrong or empty answer slip into the final result, with nobody knowing there is anything to question. - Why is crashing the wrong answer too?
Letting one failure bring the whole job down throws away all the work the other parts did correctly. One broken step should not cost you everything that succeeded around it. - So what should a step do when it cannot finish?
A step should fix the small, passing problems itself. Where it genuinely cannot, it reports back what went wrong in enough detail for the system to decide what to do next. - Is there a rule of thumb for handling failure?
Recover what you can quietly, escalate only what you cannot, and even then escalate with the full record rather than empty-handed. A handoff with no context makes the next person start from nothing. - Can I tell whether a step worked from what it returned?
No. The payload and the status are two different things, and whether the operation succeeded has to travel in its own channel rather than being guessed from the answer looking empty. - Why is an empty result not proof of failure?
An empty answer can be perfectly valid, the honest result of a question with nothing to find. Read as a failure, a genuine nothing gets treated as a broken lookup. - And why is a result coming back not proof of success?
A result that arrives might still be partial or stale, returned by something that broke partway through. So a step returning data is no evidence that the step actually worked. - Does the kind of failure change what I should do?
Entirely. A rate limit means wait and retry, a bad service account means fix the credentials rather than retry, and the service being down means go to an alternative instead. - What about when the separate results are combined at the end?
A tidy, confident summary can quietly hide that part of the evidence never arrived. Mark which parts are well-supported and which are thin, so looks-good is never mistaken for is-good.
Back to For developers. The craft around it is Working with AI.