Error Handling Recipes

The error handling recipes are copy-paste prompts for Claude Code, Codex, and Cursor that cover four jobs around a production failure: debugging, logging, recovery, and monitoring. Every recipe follows one rule: the agent attaches evidence that a check failed before the change and passes after it, so you approve evidence instead of reading every line.

This hub is for developers who hand production errors to an agent, and for tech leads who approve those fixes. You know the situation: the API returns 500s, the logs say Error: undefined, and the agent’s first fix wraps the call in try/catch so the error disappears from the dashboard but not from your users’ screens.

Which error handling recipe fits your problem?

Start from the symptom. The last column is the evidence the agent attaches to the pull request.

Your problem	Recipe	The check that proves it
A bug you can see but cannot explain: a stack trace, an intermittent failure, a leak, a race	Debugging patterns	A reproduction that fails on the unfixed code and passes after the fix
Logs that are console.log strings, lack request IDs, or leak secrets	Logging patterns	A test that asserts the structured fields and that a secret never reaches the output
A flaky dependency that takes your service down with it	Recovery patterns	A chaos or fault-injection test that kills the dependency and checks the fallback
Errors your users find before you do: no alerts, noisy alerts, no SLO	Monitoring and logging patterns	promtool test rules and a query that returns real data

Starting from nothing? Fix the logs first, because every other recipe needs evidence the agent can read. Then debug the failures you have, add recovery where a dependency keeps failing, and finish with alerts so the next failure reaches you before a customer does.

For the incident process around a fix (paging, triage, the postmortem), read AI-powered incident response. For the principle that turns every production error into a regression test, read error-driven development.

Give the agent your error-handling rules before any recipe

Without rules, an agent optimizes for a quiet log: it swallows exceptions, adds optional chaining, and returns defaults for data that must exist. Write the rules once, where each tool loads them automatically.

## Error-handling rules
- Never swallow an error: no empty catch, no catch that only logs and continues,
  no default value for data that must exist. Rethrow, or return a typed error.
- Classify every new catch: "expected sometimes" (handle it, log at warn) or
  "should never happen" (fail loudly, log at error with context).
- Log with the project logger in structured form, with the request ID. Never log
  tokens, passwords, cookies, or full request bodies.
- Every bug fix starts with a test or script that reproduces the bug and fails.
  Never edit, skip, or loosen that test to make it pass.
- Retries only for idempotent calls, with a cap, backoff, and jitter.

Cursor

Save the block as a project rule in .cursor/rules/, set to apply always. Keep the text identical to the other tools’ files so a change to the rules reaches every agent.

Claude Code

Add the block to CLAUDE.md at the repository root. Claude Code loads it in every session, including headless claude -p runs.

Codex

Add the block to AGENTS.md at the repository root. Codex reads AGENTS.md before it starts work; in a project you have not marked as trusted, it ignores the project’s AGENTS.md (Codex 0.150.0+).

The “never loosen the test” rule matters most, and a rule alone is trust, not enforcement. Protecting the oracle shows how to make the reproduction test read-only for the agent.

Copy-paste prompt: audit how this codebase handles errors

Read-only pass: do not edit files. Find every place in src/ where an error can
disappear: empty catch blocks, catch blocks that only log, promise chains with no
rejection handler, optional chaining or default values on data that must exist,
and retries without a cap. For each, give file:line, which rule it breaks
("swallowed", "no context", "unbounded retry", "secret in log"), and the user-
visible effect if it fires in production. Output one table sorted by that effect,
then name the error handling recipe that fixes the top three.

Copy-paste prompt: fix a production error with a failing test first

Here is a production error with its stack trace and request ID: <paste>.
1. Explain the cause in two sentences and quote the log lines or code that prove it.
   If the evidence is not enough, say what you need and stop.
2. Write a test that reproduces the error and run it. Show me that it fails.
3. Fix the cause, not the symptom: no new catch that hides the error.
4. Rerun the test, the full suite, the type check, and lint. Paste the output.
Do not edit the test after step 2.

How do you verify an agent’s error handling without reading every line?

Each recipe ends in a check a machine runs, and the pull request carries its output.

• Red, then green. The reproduction fails on the unfixed code and passes after the fix. A test that never failed proves nothing.
• The gates run in CI. The full suite, the type check, and lint run on the pull request, not only in the agent’s session.
• A second agent reviews the diff against the diagnosis. Run /code-review in a Claude Code session, codex exec review --uncommitted in the terminal, or Bugbot on the pull request in Cursor, and ask it to look for hidden errors: new catches, loosened assertions, defaults on required data.
• Production confirms the fix. After deploy, the error rate for that issue stays at zero through one traffic peak. The developer who shipped the fix checks it.

The developer owns the evidence; the tech lead approves when every item is present. For the full evidence table, see how to prove a bug fix without reading every line. For deliberate fault injection beyond one dependency, see error injection testing.

What breaks when agents handle errors?

Error handling failure modes and recovery

• The fix hides the error. A new try/catch, optional chaining, or a default value makes the stack trace vanish while users still see the failure. Recovery: reject the diff, and rerun the second-agent review with “does this hide errors anywhere?” as its first question.
• The reproduction turns green because the agent edited it. Recovery: git diff the test file on its own, revert it, and make the path read-only for the agent.
• A retry turns a slow dependency into an outage. Retries without jitter or a cap multiply load on a service that is already struggling. Recovery: apply the circuit breaker and jittered retry from the recovery recipe, and prove them with its chaos test.
• Logging leaks a secret. “Log the request so we can debug it” writes tokens and cookies to the log store. Recovery: add the redaction test from the logging recipe, and rotate any credential that reached the logs.
• The agent diagnoses from a paraphrase. Your summary of the error drops the detail that matters. Recovery: give it the raw stack trace, or connect a read-only error-tracking MCP server, as the debugging recipe shows.

Where to go next with error handling

Debugging patterns Five hunts, from stack trace to race condition, each proven by a check that failed first.

Logging patterns Structured, correlated, secret-safe logs the agent can query.

Recovery patterns Circuit breakers, jittered retries, and fallbacks, proven with a chaos test.

Monitoring and logging patterns Alert rules, SLO burn rates, and dashboards the agent writes and tests.

Observability MCP servers Give the agent the real error and trace instead of your summary of it.

Monitoring and observability The operate-stage workflow these recipes plug into.