Skip to content

24 · Troubleshooting

When something goes wrong with a Claude integration, an agent, Claude Code or one of this repository's labs, start here. Every page uses the same four-step structure so you can scan quickly:

Step Question it answers
Symptom What do you see? (an error, a wrong answer, a hang)
Likely cause What usually produces that symptom?
Diagnosis How do you confirm the cause, cheaply and safely?
Fix What change resolves it, and how do you stop it recurring?

As of 2026-10-24. Error messages, limits and commands change. Where a page quotes an API behaviour it is dated and links to the official docs.

Pages

Page Use it when
API errors You get an HTTP error from the Claude API (400, 401, 403, 404, 413, 429, 500, 529) or a streaming error
Prompts and outputs The call succeeds but the answer is wrong, invented, too long, in the wrong format, or refused
Tools and agents Tool calls fail, the agent loops, picks the wrong tool or never finishes
Claude Code Claude Code ignores CLAUDE.md, keeps prompting, a hook misfires, or settings do not apply
MCP An MCP server will not connect, authenticate or show its tools
RAG Retrieval returns the wrong passages, misses obvious ones, or serves outdated content
Labs and repository A lab will not run, mock and live mode behave differently, the virtual environment is broken, or a repo check fails

A general method

flowchart TD
  A[Symptom] --> B{Reproducible?}
  B -- no --> C[Add logging: request id, model, params, stop_reason, usage]
  C --> B
  B -- yes --> D[Shrink to the smallest failing input]
  D --> E[Form one hypothesis]
  E --> F[Change one thing]
  F --> G{Fixed?}
  G -- no --> E
  G -- yes --> H[Add a regression test or eval case]
  1. Capture the evidence first: the request-id response header, model ID, parameters, stop_reason, usage and the exact error body. Never log API keys or unnecessary personal data.
  2. Reproduce small: strip the request to the minimum that still fails.
  3. Change one variable at a time and keep notes.
  4. Prevent recurrence: a unit test, an eval case, a hook or a monitoring alert.

Escalation

Related: 15 · Production operations, 14 · Diagnosing failures.