Claude Code Error Message Decoder: logs से reproducible fix तक

Claude Code नया इस्तेमाल करते समय लंबा error message paste करके “इसे ठीक करो” कहना आसान लगता है. कभी-कभी यह काम कर जाता है, लेकिन यह भरोसेमंद workflow नहीं है. Claude Code अपने आप नहीं जानता कि आपने कौन सा command चलाया, कौन से environment variables थे, Node version क्या था, या CI और आपकी machine में क्या फर्क है. बेहतर तरीका है error को reproducible bug report में बदलना, फिर Claude Code से likely root cause, next commands और verification plan मांगना.

यह guide stack traces, TypeScript errors, Node.js runtime logs, Docker/Kubernetes logs और GitHub Actions failures को practical तरीके से handle करती है. Official reference के लिए Claude Code common workflows, Claude Code troubleshooting और Claude Code settings देखें.

मुख्य workflow: guess नहीं, reproduce करें

Error message कोई पहेली नहीं है. यह evidence है. Evidence पूरा बचाइए, फिर noise कम कीजिए.

flowchart TD
  A["Fail हुए command का output save करें"] --> B["Full log रखें, noise कम करें"]
  B --> C["Claude Code से hypotheses और reproduction steps मांगें"]
  C --> D["सबसे छोटा failing case बनाएं"]
  D --> E["Fix के बाद वही command फिर चलाएं"]
  E --> F["Prevention जोड़ें: test, checklist या CLAUDE.md"]

Error source	Claude Code को दें	Output मांगें	खुद verify करें
TypeScript	पूरा tsc --noEmit --pretty false output और file paths	Broken type contract, safe fix, risky fix	any या ts-ignore से छुपाया नहीं गया
Node.js stack trace	पहली Error line, app frames, trigger input	पहला useful app frame, reproduction input	वही input local पर fail हो
Docker/Kubernetes	describe, previous logs, events	OOM, env, probe, image या app error category	Evidence line और kubectl command
GitHub Actions	Failed job log और changed files	Failed step, local command, CI-only differences	Local और CI दोनों pass

Use case 1: npm और tsc errors save करें

Terminal की आखिरी lines ही copy न करें. Original output पहले save करें.

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

अब Claude Code से direct fix नहीं, debugging plan मांगें.

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.
"

Confidence level मांगना जरूरी है. अगर Claude Code 60% sure है, तो patch से पहले अगला confirmation command चाहिए.

Use case 2: Node.js stack trace छोटा करें

Node.js stack trace में node_modules बहुत आता है. Full log रखें और triage के लिए छोटा version बनाएं.

// 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"));

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

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
"

यह script diagnosis नहीं करती. यह सिर्फ dependency frames कम करके application frame दिखाती है.

Use case 3: TypeScript error को contract break की तरह पढ़ें

Type X is not assignable to type Y का आम मतलब है: caller ने जिस data shape को भेजा, callee उससे अलग shape expect कर रहा था. Type एक contract है.

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 Hindi 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.
"

इससे असली fix और compiler को चुप कराने वाला fix अलग दिखता है. User | null में अक्सर logged-out state handle करना, API response validate करना या test fixture ठीक करना सही होता है.

Use case 4: Kubernetes logs से confirmation commands निकालें

CrashLoopBackOff root cause नहीं, symptom है.

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

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.
"

अगर answer evidence line नहीं दिखाता, तो वह conclusion नहीं, सिर्फ hypothesis है.

Use case 5: GitHub Actions failure triage करें

CI logs में असली failure बाद की बहुत सारी output में छिप जाता है. Log निकालें और local reproduction अलग करें.

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.
"

यह flaky tests, timezone difference, missing secrets, cache problem और permissions issue में काम आता है.

Copy-paste bug report template

# 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

सिर्फ आखिरी तीन lines paste न करें. Real cause अक्सर बीच में होती है.

Exact command न छोड़ें. npm test, npm run build और vitest --run src/foo.test.ts अलग context देते हैं.

TypeScript fix के नाम पर any, ts-ignore या test delete करना default न बनाएं. यह emergency workaround हो सकता है, safe habit नहीं.

Secrets paste न करें. API keys, cookies, JWT और database URLs redact करें. Team use में official settings देखकर permissions तय करें.

Fix के बाद पहले वही command चलाएं जो fail हुआ था. फिर lint, build और CI तक जाएं.

ClaudeCodeLab training, templates और consultation

Solo work में इस article के prompts काफी हैं. Team में असली काम है: कौन से logs share होंगे, कौन से fixes forbidden होंगे, CI triage कैसे होगा, और reviewer को कौन सा evidence चाहिए.

ClaudeCodeLab reusable debugging prompts, bug-report templates, CI triage checklists और CLAUDE.md rules बनाने के लिए Claude Code products and templates और Claude Code training and consultation देता है.

आगे पढ़ें: Claude Code error diagnosis, Claude Code debugging techniques और Claude Code logging and monitoring.

निष्कर्ष

लक्ष्य यह नहीं है कि Claude Code बेहतर guess करे. लक्ष्य यह है कि उसे इतना evidence मिले कि वह अगला reproducible step दे सके. Failed command save करें, full log रखें, noise सावधानी से घटाएं, confidence मांगें और उसी command से verify करें.

इस workflow को ClaudeCodeLab maintenance में आजमाने के बाद Masa ने पाया कि सबसे बड़ा फायदा debugging के पहले 10 मिनट में मिलता है. tsc --pretty false output save करना, full log रखकर stack trace छोटा करना, और CI failure को job, step, command, reproduction में तोड़ना Claude Code की suggestions को blindly trust करने के बजाय verify करने लायक बनाता है.