Error Resolver

A first-principle approach to diagnosing and resolving errors across all languages and frameworks.

Core Philosophy

The 5-step Error Resolution Process:

1. CLASSIFY -> 2. PARSE -> 3. MATCH -> 4. ANALYZE -> 5. RESOLVE

| | | | |

What type? Extract key Known Root cause Fix +

information pattern? analysis Prevent

Quick Start

When you encounter an error:

Paste the full error

(including stack trace if available)

Provide context

(what were you trying to do?)

Share relevant code

(the file/function involved)

Error Classification Framework

Primary Categories

Category

Indicators

Common Causes

Syntax

Parse error, Unexpected token

Typos, missing brackets, invalid syntax

Type

TypeError, type mismatch

Wrong data type, null/undefined access

Reference

ReferenceError, NameError

Undefined variable, scope issues

Runtime

RuntimeError, Exception

Logic errors, invalid operations

Network

ECONNREFUSED, timeout, 4xx/5xx

Connection issues, wrong URL, server down

Permission

EACCES, PermissionError

File/directory access, sudo needed

Dependency

ModuleNotFound, Cannot find module

Missing package, version mismatch

Configuration

Config error, env missing

Wrong settings, missing env vars

Database

Connection refused, query error

DB down, wrong credentials, bad query

Memory

OOM, heap out of memory

Memory leak, large data processing

Secondary Attributes

Severity

Fatal / Error / Warning / Info

Scope

Build-time / Runtime / Test-time

Origin

User code / Framework / Third-party / System Analysis Workflow Step 1: Classify Identify the error category by examining: Error name/code (e.g., ENOENT , TypeError ) Error message keywords Where it occurred (compile, runtime, test) Step 2: Parse Extract key information: - Error code: [specific code if any] - File path: [where the error originated] - Line number: [exact line if available] - Function/method: [context of the error] - Variable/value: [what was involved] - Stack trace depth: [how deep is the call stack] Step 3: Match Patterns Check against known error patterns: See patterns/ directory for language-specific patterns Match error signatures to known solutions Check replay history for previous solutions Step 4: Root Cause Analysis Apply the 5 Whys technique: Error: Cannot read property 'name' of undefined Why 1? -> user object is undefined Why 2? -> API call returned null Why 3? -> User ID doesn't exist in database Why 4? -> ID was from stale cache Why 5? -> Cache invalidation not implemented Root Cause: Missing cache invalidation logic Step 5: Resolve Generate actionable solution: Immediate fix - Get it working now Proper fix - The right way to solve it Prevention - How to avoid in the future Output Format When resolving an error, provide:

Error Diagnosis

Classification: [Category] / [Severity] / [Scope] Error Signature: - Code: [error code] - Type: [error type] - Location: [file:line]

Root Cause

[Explanation of why this error occurred] Contributing Factors: 1. [Factor 1] 2. [Factor 2]

Solution

Immediate Fix

[Quick steps to resolve]

Code Change

[Specific code to add/modify]

Verification

[How to verify the fix works]

Prevention

[How to prevent this error in the future]

Replay Tag

[Unique identifier for this solution - for future reference] Replay System The replay system records successful solutions for future reference. Recording a Solution After resolving an error, record it:

Create solution record in project

mkdir -p .claude/error-solutions

Solution file format: [error-type]-[hash].yaml

Solution Record Format

.claude/error-solutions/[error-signature].yaml

id : "nodejs-module-not-found-express" created : "2024-01-15T10:30:00Z" updated : "2024-01-20T14:22:00Z" error : type : "dependency" category : "ModuleNotFound" language : "nodejs" pattern : "Cannot find module 'express'" context : "npm project, missing dependency" diagnosis : root_cause : "Package not installed or node_modules corrupted" factors : - "Missing npm install after git clone" - "Corrupted node_modules directory" - "Package not in package.json" solution : immediate : - "Run: npm install express" proper : - "Check package.json has express listed" - "Run: rm -rf node_modules && npm install" code_change : null verification : - "Run the application again" - "Check express is in node_modules" prevention : - "Add npm install to project setup docs" - "Use npm ci in CI/CD pipelines" metadata : occurrences : 5 last_resolved : "2024-01-20T14:22:00Z" success_rate : 1.0 tags : [ "nodejs" , "npm" , "dependency" ] Replay Lookup When encountering an error: Generate error signature from the error message Search .claude/error-solutions/ for matching patterns If found, apply the recorded solution If new, proceed with full analysis and record the solution Error Signature Generation signature = hash( error_type + error_code + normalized_message + # remove specific values language + framework ) Example transformations: Cannot find module 'express' -> Cannot find module '{module}' TypeError: Cannot read property 'name' of undefined -> TypeError: Cannot read property '{prop}' of undefined Debug Commands Useful commands during debugging: Node.js

Verbose error output

NODE_DEBUG

* node app.js

Memory debugging

node --inspect app.js

Check installed packages

npm ls [ package-name ]

Verify package.json

npm ls --depth = 0 Python

Debug mode

python -m pdb script.py

Check installed packages

pip show [ package-name ] pip list General

Check file permissions

ls -la [ file ]

Check port usage

lsof -i : [ port ] netstat -an | grep [ port ]

Check environment variables

env | grep [ VAR_NAME ] printenv [ VAR_NAME ]

Check disk space

df -h

Check memory

free -m

Linux

vm_stat

macOS

Common Debugging Patterns Pattern 1: Binary Search When the error location is unclear: Comment out half the code If error persists, it's in the remaining half Repeat until you find the exact line Pattern 2: Minimal Reproduction Create the smallest code that reproduces the error: Start with empty file Add code piece by piece Stop when error appears That's your minimal repro case Pattern 3: Rubber Duck Debugging Explain the problem out loud (or to Claude): What should happen? What actually happens? What changed recently? What assumptions am I making? Pattern 4: Git Bisect Find which commit introduced the bug: git bisect start git bisect bad

current commit is bad

git bisect good [ last-known-good-commit ]

Git will checkout commits for you to test

git bisect good/bad

mark each as good or bad

git bisect reset

when done

Reference Files patterns/ - Language-specific error patterns nodejs.md - Node.js common errors python.md - Python common errors react.md - React/Next.js errors database.md - Database errors docker.md - Docker/container errors git.md - Git errors network.md - Network/API errors analysis/ - Analysis methodologies stack-trace.md - Stack trace parsing guide root-cause.md - Root cause analysis techniques replay/ - Replay system solution-template.yaml - Template for recording solutions