error-analysis

Error Analysis

Overview

Errors are information. Stack traces are maps. Reading them carefully reveals root cause faster than guessing.

Core principle: Classify the error before diagnosing it. Different error classes have different diagnostic approaches.

Relationship to systematic-debugging: Use error-analysis to understand WHAT the error is and WHERE it originates. Use systematic-debugging to find WHY it happens and implement the fix.

Iron Law:

READ THE ENTIRE STACK TRACE BEFORE FORMING ANY HYPOTHESIS

The answer is almost always in the error message. Most debugging failures are reading failures.

When to Use

• Encountering a new error message
• Stack trace from production logs
• Unexpected application behavior (silent failure)
• CI/CD pipeline failures
• Type errors, runtime errors, build errors

Error Classification

First, classify the error type:

Class	Symptoms	Common Causes
Syntax Error	Fails at parse/compile time	Typo, missing bracket, wrong syntax
Type Error	TypeScript compiler error	Wrong type, missing null check
Runtime Error	Fails during execution	Null reference, division by zero
Logic Error	Wrong output, no crash	Algorithm mistake, off-by-one
Network Error	Connection failures	Service down, timeout, firewall
Config Error	App won't start	Missing env var, wrong path
Concurrency Error	Intermittent failures	Race condition, deadlock
Memory Error	Growing memory, crash	Memory leak, large allocation

Reading Stack Traces

Anatomy of a Stack Trace

Error: Cannot read properties of undefined (reading 'name')  ← Error type + message
    at RulesService.getRule (/app/src/rules/rules.service.ts:42:18)  ← Closest to error
    at McpService.handleTool (/app/src/mcp/mcp.service.ts:87:32)
    at McpModule.dispatch (/app/src/mcp/mcp.module.ts:23:12)  ← Furthest from error

Reading order:

1. Error message — WHAT went wrong
2. First frame — WHERE it broke (your code closest to error)
3. Subsequent frames — HOW we got there (call chain)
4. Last frame — ENTRY POINT that triggered the chain