Development
Debugging and Error Recovery
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error.
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error.
Systematic debugging with structured triage. When something breaks, stop adding features and follow a structured process.
When anything unexpected happens:
1. STOP adding features or making changes
2. PRESERVE evidence (error output, logs, repro steps)
3. DIAGNOSE using the triage checklist
4. FIX the root cause
5. GUARD against recurrence
6. RESUME only after verification passes
Make the failure happen reliably. If you can't reproduce it, you can't fix it with confidence.
Can you reproduce the failure?
├── YES → Proceed to Step 2
└── NO
├── Gather more context (logs, environment details)
├── Try reproducing in a minimal environment
└── If truly non-reproducible, document conditions and monitor
Narrow down WHERE the failure happens:
Which layer is failing?
├── UI/Frontend → Check console, DOM, network tab
├── API/Backend → Check server logs, request/response
├── Database → Check queries, schema, data integrity
├── Build tooling → Check config, dependencies, environment
├── External service → Check connectivity, API changes
└── Test itself → Check if the test is correct
Use bisection for regression bugs:
git bisect start
git bisect bad # Current commit is broken
git bisect good <known-good-sha> # This commit worked
git bisect run npm test -- --grep "failing test"
Create the minimal failing case:
Fix the underlying issue, not the symptom:
Symptom: "The user list shows duplicate entries"
Symptom fix (bad):
→ Deduplicate in the UI component: [...new Set(users)]
Root cause fix (good):
→ The API endpoint has a JOIN that produces duplicates
→ Fix the query, add a DISTINCT, or fix the data model
Ask: "Why does this happen?" until you reach the actual cause.
Write a test that catches this specific failure:
// The bug: task titles with special characters broke the search
it('finds tasks with special characters in title', async () => {
await createTask({ title: 'Fix "quotes" & <brackets>' });
const results = await searchTasks('quotes');
expect(results).toHaveLength(1);
expect(results[0].title).toBe('Fix "quotes" & <brackets>');
});
# Run the specific test
npm test -- --grep "specific test"
# Run the full test suite
npm test
# Build the project
npm run build
# Manual spot check if applicable
npm run dev
Test fails after code change:
├── Did you change code the test covers?
│ └── YES → Check if the test or the code is wrong
│ ├── Test is outdated → Update the test
│ └── Code has a bug → Fix the code
├── Did you change unrelated code?
│ └── YES → Likely a side effect → Check shared state
└── Test was already flaky?
└── Check for timing issues, order dependence
Build fails:
├── Type error → Read the error, check the types
├── Import error → Check the module exists, exports match
├── Config error → Check build config files
├── Dependency error → Check package.json, run npm install
└── Environment error → Check Node version, OS compatibility
Runtime error:
├── TypeError: Cannot read property 'x' of undefined
│ └── Something is null/undefined that shouldn't be
├── Network error / CORS
│ └── Check URLs, headers, server CORS config
├── Render error / White screen
│ └── Check error boundary, console, component tree
└── Unexpected behavior (no error)
└── Add logging at key points, verify data at each step
// Safe default + warning (instead of crashing)
function getConfig(key: string): string {
const value = process.env[key];
if (!value) {
console.warn(`Missing config: ${key}, using default`);
return DEFAULTS[key] ?? '';
}
return value;
}
// Graceful degradation (instead of broken feature)
function renderChart(data: ChartData[]) {
if (data.length === 0) {
return <EmptyState message="No data available" />;
}
try {
return <Chart data={data} />;
} catch (error) {
console.error('Chart render failed:', error);
return <ErrorState message="Unable to display chart" />;
}
}
After fixing a bug: