7.3 - Debugging and Operational Issue Resolution

Build exercise: Fault-injection lab and escalation runbook

Intermediate · 75 minutes

You'll practice:

• Diagnose configuration-loading faults with /context, /status, /hooks, /mcp and claude doctor
• Bisect a configuration problem with --safe-mode and a clean CLAUDE_CONFIG_DIR
• Handle API errors with typed exceptions and capture request IDs
• Assemble an escalation packet and triage table for your own platform

1. In a scratch repository, inject five faults: (a) a hook whose matcher is a JSON array, (b) a skill saved as .claude/skills/deploy.md instead of a folder with SKILL.md, (c) a .mcp.json placed inside .claude/, (d) a rule stored in services/api/CLAUDE.md that you test by asking Claude to create a new file there, (e) a deny rule Bash(rm *) tested against a scratch file removed with /bin/rm. For each, record the symptom, the first command you ran, the layer, and the fix.

   These are documented, common causes of 'my configuration is ignored'. Reproducing them trains you to reach for the loading diagnostics before rewriting prompts.

   You should see: Five rows of notes. For (a) claude doctor reports the settings problem and /hooks shows nothing from that file; (b) the skill is absent from /skills; (c) /mcp shows no server; (d) /context lacks the file until Claude reads a file in that directory; (e) the deny rule does not stop the alternate form.

   Hints

   1. For each fault, which single command would show whether the thing loaded at all?

   2. Use /hooks, /skills, /mcp, /context and /permissions for the first look, claude doctor for invalid settings, and compare against the debugging table in the docs for the fix.

   3. Fixes: matcher becomes a string such as "Edit|Write"; skill moves to .claude/skills/deploy/SKILL.md; .mcp.json moves to the repository root with servers under mcpServers; move the rule to root or a path-scoped rule (or a hook if it must always run); use a sandbox or PreToolUse hook when a Bash deny must hold.

2. Run a bisect on a session that misbehaves: first claude --safe-mode, then a clean session using an empty CLAUDE_CONFIG_DIR from a directory with no project configuration. Reintroduce user config, project config and MCP servers one at a time. Write a bisect log naming the step that reintroduced the problem.

   A methodical bisect turns 'something is off' into a named cause and avoids changing several things at once.

   You should see: A log with one row per step (safe mode, clean dir, +user config, +project config, +MCP) and a clear PASS or FAIL per row, ending in a single culprit.

   Hints

   1. What does safe mode disable, and what does it deliberately leave on?

   2. If safe mode fixes it, the cause is CLAUDE.md, skills, plugins, hooks, MCP servers, commands or agents. If not, use a clean config directory and check /status for managed settings and environment variables.

   3. Commands: claude --safe-mode; then cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude (expect first-run screens and a fresh login); finally copy files back one by one, or launch from the project directory, and re-test after each change.

3. Write a small Python script that makes three failing calls (an invalid model name, an invalid request, and a client with an obviously fake key) and prints the status code, the request-id header, the elapsed time and the message for each, catching the most specific exception classes first. Confirm that none of the 4xx responses was retried.

   It shows typed exception handling, the request ID on the exception's response, and the deterministic-4xx rule in one place.

   You should see: Three lines of output with different status codes (record what you observe rather than assuming), a non-empty request-id for each response the API returned, and elapsed times near a single round trip rather than several seconds of backoff.

   Hints

   1. Which exception class is the parent of the status-specific errors, and which one covers network failures with no response?

   2. Catch anthropic.APIStatusError for anything that carried a status, anthropic.APIConnectionError separately, read e.status_code and e.response.headers.get('request-id'), and time each call.

   3. import time, anthropic
      MSG = [{'role': 'user', 'content': 'hi'}]
      def probe(label, client, **kw):
          t = time.time()
          try:
              client.messages.create(**kw)
          except anthropic.APIStatusError as e:
              print(label, e.status_code, e.response.headers.get('request-id'), round(time.time() - t, 2), str(e)[:100])
          except anthropic.APIConnectionError as e:
              print(label, 'no response', e.__cause__)
      ok = anthropic.Anthropic()
      probe('bad-model', ok, model='not-a-real-model', max_tokens=16, messages=MSG)
      probe('bad-request', ok, model='claude-sonnet-5', max_tokens=16, messages=[])
      probe('bad-key', anthropic.Anthropic(api_key='sk-ant-obviously-fake'), model='claude-sonnet-5', max_tokens=16, messages=MSG)

4. Correlate a Claude Code failure across logs: start a session with --debug-file ./cc-debug.log and OpenTelemetry console exporters enabled, provoke a failing API call, then find the same failure in the debug log and in the claude_code.api_error event and record the request_id and session.id.

   Operations teams need one identifier that links a user's report, the client log and the server-side record.

   You should see: An api_error event with the error details and (when the server returned one) request_id, plus a client_request_id and matching lines in the debug file. Your notes state which identifier you would give support.

   Hints

   1. Which environment variables switch telemetry on, and which exporters print to the console?

   2. Set CLAUDE_CODE_ENABLE_TELEMETRY=1 with the logs exporter set to console, run claude with --debug-file, cause a failure such as an invalid model name, and search both outputs for the error.

   3. CLAUDE_CODE_ENABLE_TELEMETRY=1 OTEL_LOGS_EXPORTER=console claude --debug-file ./cc-debug.log, then grep -n 'error' ./cc-debug.log and look for a claude_code.api_error event in the console output. Prompt text is not logged unless you opt in.

5. Write an escalation packet template and a one-page triage table for your platform. Fill the template with the failure from step 3 or 4, check the Claude status page, and state whether you would escalate and to whom.

   The packet is what turns an anecdote into an investigation, and the triage table tells on-call staff which layer to check first.

   You should see: A template with request IDs, timestamps and time zone, model and provider, Claude Code version, /status output, minimal repro, ruled-out causes and impact, and a triage table that separates 4xx (owner: application team) from 5xx and 529 (check the status page, then support).

   Hints

   1. What would an engineer who has never seen your system need to reproduce the problem?

   2. Include identifiers first, then environment, then the smallest repro, then what you tried. Add a rule about not attaching credentials, transcripts or heap snapshots.

   3. Template: 1) Impact and time window; 2) request-id values; 3) model, provider, SDK or Claude Code version; 4) /status output; 5) minimal repro; 6) ruled out (config bisect result, status page check); 7) attachments (diagnostics only, no keys).