Claude Code Error Message Decoder: Turn Logs into Reproducible Fixes

When you are new to Claude Code, it is tempting to paste a scary error message and ask, “Fix this.” That works sometimes, but it also teaches the wrong habit. Claude Code cannot automatically know your shell command, environment variables, package versions, or what you tried just before the failure. The stronger workflow is to turn the error into a reproducible bug report, then ask Claude Code for likely causes, next commands, and a verification plan.

This guide covers stack traces, TypeScript errors, Node.js runtime logs, Docker/Kubernetes logs, and GitHub Actions failures. For official background, keep Claude Code common workflows, Claude Code troubleshooting, and Claude Code settings nearby.

The Workflow

Do not treat an error message as a riddle. Treat it as evidence.

flowchart TD
  A["Save the failing command output"] --> B["Reduce noisy frames without deleting the full log"]
  B --> C["Ask Claude Code for hypotheses and reproduction steps"]
  C --> D["Build the smallest failing example"]
  D --> E["Patch and rerun the same command"]
  E --> F["Add prevention: test, checklist, or CLAUDE.md rule"]

Error source	Give Claude Code	Ask for	Verify yourself
TypeScript	Full tsc --noEmit --pretty false output and file paths	Broken type contract, safe fix, risky fix to avoid	No any, no ts-ignore, strict mode still on
Node.js stack trace	First error line, app frames, input that triggered it	First useful application frame and minimal failing input	Same input reproduces locally
Docker/Kubernetes	describe, previous logs, events	OOM, env var, probe, image, or app failure category	Evidence line and confirming kubectl command
GitHub Actions	Failed job log and changed files	Failed step, local command, CI-only differences	Local command and rerun CI both pass

Use Case 1: Capture npm and tsc Errors

The first mistake is losing the original output. Save it before shortening it.

mkdir -p tmp/error-cases
npm test 2>&1 | tee tmp/error-cases/test.log
npx tsc --noEmit --pretty false 2>&1 | tee tmp/error-cases/tsc.log

Then ask for a debugging plan instead of a magic answer.

claude -p "
I need a reproducible fix, not a guess.

Read these files if they exist:
- tmp/error-cases/test.log
- tmp/error-cases/tsc.log

Return:
1. One-line failure summary
2. Likely root cause with confidence level
3. Minimal reproduction steps
4. Next 3 commands to run
5. Smallest safe code change to try
6. Verification command after the fix

Do not hide TypeScript errors with any or ts-ignore.
"

The confidence level matters. If Claude Code is only 60% sure, you want the next command that raises or lowers that confidence, not a confident-sounding patch.

Use Case 2: Minimize a Node.js Stack Trace

Long stack traces are hard to read because dependency frames dominate the output. Keep the full log, then create a shorter copy for triage.

// scripts/minimize-stacktrace.mjs
import { readFileSync } from "node:fs";

const input = readFileSync(0, "utf8");
const lines = input.split(/\r?\n/);
const kept = [];
let dependencyFrames = 0;

for (const line of lines) {
  const isStackFrame = /^\s+at /.test(line);
  const isDependencyFrame = line.includes("node_modules");

  if (!isStackFrame || !isDependencyFrame || dependencyFrames < 3) {
    kept.push(line);
  }

  if (isStackFrame && isDependencyFrame) {
    dependencyFrames += 1;
  }
}

const important = kept.filter((line) =>
  /Error:|TypeError:|ReferenceError:|SyntaxError:|Caused by:|^\s+at |src\/|app\/|packages\//.test(line)
);

console.log(important.slice(0, 80).join("\n"));

Run it like this:

node scripts/minimize-stacktrace.mjs < tmp/error-cases/test.log > tmp/error-cases/test.min.log

Now ask Claude Code to identify the first useful frame.

claude -p "
Analyze tmp/error-cases/test.min.log first.
If the minimized log is not enough, ask for the full log instead of guessing.

Explain:
- Which application frame is the first useful frame
- What input or state is needed to reproduce it
- Whether this looks like async timing, null data, missing env, or dependency mismatch
- The smallest test that would fail before the fix
"

Use Case 3: Read TypeScript Errors as Broken Contracts

Type X is not assignable to type Y usually means one piece of code promised one data shape and another piece supplied a different shape. Ask Claude Code to explain the contract, not just silence the compiler.

claude -p "
Explain this TypeScript error as a broken contract between caller and callee.

Use this output:
$(npx tsc --noEmit --pretty false 2>&1)

Return a table with:
- Error location
- Plain English explanation
- Data shape expected
- Data shape actually provided
- Safe fix
- Risky fix to avoid

Do not suggest any, ts-ignore, or disabling strict mode unless there is no other option.
"

This prompt separates real fixes from compiler suppression. For example, a User | null error should push you toward handling the logged-out state, validating API data, or fixing test fixtures, not casting the value into a lie.

Use Case 4: Turn Kubernetes Logs into Confirmation Commands

CrashLoopBackOff is not a root cause. It is a symptom. Collect the pod description, previous logs, and events.

kubectl get pod -n app
kubectl describe pod web-abc123 -n app > tmp/error-cases/pod.describe.txt
kubectl logs web-abc123 -n app --previous > tmp/error-cases/pod.previous.log
kubectl get events -n app --sort-by=.lastTimestamp > tmp/error-cases/events.log

Then require evidence and the next kubectl command.

claude -p "
Triage this Kubernetes crash.

Files:
- tmp/error-cases/pod.describe.txt
- tmp/error-cases/pod.previous.log
- tmp/error-cases/events.log

Return:
1. Most likely category: OOMKilled, missing env, image pull, app exception, probe failure, or dependency outage
2. Evidence lines from the logs
3. One kubectl command to confirm each remaining hypothesis
4. Temporary mitigation
5. Permanent fix
6. Rollback check

If evidence is insufficient, say what command is missing.
"

If the answer cannot point to an evidence line, treat it as a hypothesis.

Use Case 5: Triage GitHub Actions Failures

CI failures often hide the real problem behind pages of downstream output. Pull the log and ask Claude Code to separate local reproduction from CI-only differences.

gh run list --limit 5
gh run view RUN_ID --log > tmp/error-cases/github-actions.log

claude -p "
You are triaging a GitHub Actions failure.

Analyze tmp/error-cases/github-actions.log and return:
1. Failed job and failed step
2. Exact command that failed
3. Whether this should reproduce locally
4. Local reproduction command
5. CI-only differences to inspect: Node version, env vars, cache, timezone, OS, permissions
6. Smallest patch to try
7. Verification plan for local and CI

Do not assume the root cause if the log only shows a downstream symptom.
"

This is especially useful for flaky tests, timezone bugs, missing secrets, and package-manager cache failures.

Copy-Paste Bug Report Template

Use this before asking Claude Code to edit files.

# Bug report: short title

## Goal
What I was trying to do:

## Environment
- OS:
- Node version:
- Package manager:
- Branch:
- Commit:

## Exact command
```bash
paste the exact command here
```

## Expected result
What should have happened:

## Actual result
What happened instead:

## Logs
Paste the full error or attach the saved log file path.

## Minimal reproduction
Smallest steps that still fail:

## What I already tried
- Attempt 1:
- Attempt 2:

## Verification plan
Command that must pass after the fix:

Common Pitfalls

Do not paste only the last three lines. The last line is usually the failure result, not the first cause.

Do not omit the command you ran. npm test, npm run test:unit, and vitest --run src/foo.test.ts can fail for different reasons.

Do not accept any, ts-ignore, or deleted tests as a default TypeScript fix. Those are sometimes emergency moves, but they are not beginner-safe defaults.

Do not paste secrets. Redact API keys, cookies, JWTs, and database URLs before sharing logs. For teams, review Claude Code permissions and configuration in the official settings documentation.

Do not verify with a different command first. Rerun the command that failed, then broaden to lint, build, and CI.

Training, Templates, and Consultation

For solo work, the prompts above are enough to start. For teams, the hard part is standardizing what logs may be shared, which fixes are forbidden, how CI failures are triaged, and what evidence reviewers require.

ClaudeCodeLab provides Claude Code products and templates plus Claude Code training and consultation for teams that want reusable debugging prompts, bug-report templates, CI triage checklists, and CLAUDE.md rules instead of one-off fixes.

Related reading: Claude Code error diagnosis, Claude Code debugging techniques, and Claude Code logging and monitoring.

Conclusion

The goal is not to make Claude Code guess harder. The goal is to give it enough evidence to produce a reproducible next step. Save the failing command, keep the full log, reduce noise carefully, ask for hypotheses with confidence, and verify with the same command that failed.

After testing the workflow in real ClaudeCodeLab maintenance, Masa found the biggest gain in the first 10 minutes of debugging. Saving tsc --pretty false, minimizing stack traces without deleting the full log, and forcing CI failures into “job, step, command, reproduction” made Claude Code’s suggestions easier to verify instead of blindly trust.