error-analysis

name	error-analysis
description	Use when encountering error messages, stack traces, or unexpected application behavior. Provides structured analysis to understand root cause before attempting any fix.
allowed-tools	Read, Grep, Glob, Bash(git:*)

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

Stack Trace Analysis Template

## Error Analysis

**Error type:** [TypeError / ReferenceError / etc.]
**Error message:** [Exact message]
**File:** [filename:line:column]
**Function:** [function where error occurred]

**Call chain:** (read bottom to top)
1. Entry: [how it started]
2. → [intermediate call]
3. → [proximate cause]

**Initial hypothesis:** [What do I think is undefined/null/wrong?]
**Evidence needed:** [What do I need to verify the hypothesis?]

Common Error Patterns

// ❌ "Cannot read properties of undefined (reading 'X')"
// → Something is undefined that you expected to exist
// → Look at the line: what object is being accessed?
// → Trace back: where was this object supposed to come from?

const user = await getUser(id);
console.log(user.name); // → user is undefined when id not found
// Fix: check if user exists before accessing properties

// ❌ "is not a function"
// → Called something that isn't a function
// → Often: wrong import, undefined module, this binding issue
import { something } from './module'; // wrong path → undefined
something(); // → TypeError: something is not a function

// ❌ "Cannot find module"
// → Module doesn't exist at specified path
// → Check: path correct? file exists? compiled?

// ❌ "ENOENT: no such file or directory"
// → File system path doesn't exist
// → Check: relative vs absolute path, working directory

Diagnostic Process

Phase 1: Classify and Locate

1. What class of error is this? (see table above)
2. What file and line number? (first frame in stack)
3. What was the application doing when it failed?
   (context: which API endpoint, which user action, which test)
4. Is it reproducible? (always / sometimes / once)
5. When did it start? (new error or regression?)

Phase 2: Understand the Context

// For "Cannot read properties of undefined"
// Add temporary logging to understand what's actually there:

// Before:
const result = await this.rulesService.getRule(name);
return result.content; // ← crashes

// Add logging:
const result = await this.rulesService.getRule(name);
console.error('DEBUG result:', JSON.stringify(result, null, 2));
return result.content;

Common context questions:

• What is the actual value vs expected value?
• What are the function inputs?
• What state was the application in?
• Is this error path tested?

Phase 3: Trace to Origin

Follow the error backward through the call chain:

Frame 1: rules.service.ts:42 — result.content crashes
→ result is undefined
→ What could make getRule return undefined?

Frame 2: rules.service.ts:35 — find() returns undefined when no match
→ Why didn't it find the rule?

Frame 3: rules.service.ts:28 — rules array
→ How was rules array populated?
→ Ah: readRulesDirectory() failed silently on missing directory
→ ROOT CAUSE: directory path wrong, no error thrown

Phase 4: Form Hypothesis

**Hypothesis:** [Specific, testable statement]

Example: "The rules directory path is built from `__dirname` which
resolves to the dist/ folder in production, but .ai-rules is at
the project root, so the path is wrong."

**Evidence to gather:**
- Log the actual `rulesDir` path at startup
- Check if directory exists at that path in production

**Falsification:** If the path is correct, this hypothesis is wrong

Error Catalog

TypeScript Errors

// TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'
// → Type mismatch. Use explicit casting only if you know the type is correct.

// TS2339: Property 'X' does not exist on type 'Y'
// → Accessing property that doesn't exist. Check interface definition.

// TS7006: Parameter 'X' implicitly has an 'any' type
// → TypeScript strict mode requires explicit types. Add the type.

// TS2532: Object is possibly 'undefined'
// → Add null check: if (x !== undefined) or use optional chaining x?.y

Node.js Runtime Errors

ECONNREFUSED → Service not running or wrong port
EADDRINUSE   → Port already in use
ENOENT       → File/directory doesn't exist
EMFILE       → Too many open file handles (leak)
ENOMEM       → Out of memory

NestJS / MCP Errors

// "Nest can't resolve dependencies"
// → Circular dependency or missing provider in module
// → Check: is the service in the module's providers array?

// "Cannot GET /endpoint" (404)
// → Route not registered or wrong HTTP method
// → Check: @Controller prefix + @Get/Post path

// MCP: "Method not found"
// → Tool/Resource/Prompt name not registered
// → Check: capability registration in McpService

Quick Reference

Error Pattern	First Check
undefined reading 'X'	What should X be? Where does it come from?
is not a function	Is the import correct? Is it actually exported?
Cannot find module	Does the file exist? Is the path correct?
ENOENT	Is the file path absolute? Does it exist?
Intermittent failure	Is there shared mutable state? Race condition?
Works locally, fails in CI	Environment variable missing? Path difference?

Output Format

## Error Analysis Summary

**Error:** [class] — [message]
**Location:** [file:line]
**Reproducible:** Yes / No / Intermittent

**Root Cause:** [One clear sentence]

**Evidence:** [What confirms the root cause]

**Fix:** [What needs to change]
**Prevents recurrence:** [Test to add or check to add]

→ Hand off to systematic-debugging skill for implementation