Error Pattern Analysis
Analyze errors captured from Claude Code sessions to identify patterns and get actionable insights.
Quick Start
/errors # Batch analysis of historical error patterns
/debug # CC 2.1.30 real-time debug for current sessionWhen to Use Which
| Command | Purpose | Scope |
|---|---|---|
/errors | Batch analysis of error patterns (last 24h/7d) | Historical patterns |
/debug | Real-time debug of current session state | Current session |
/ork:fix-issue | Full RCA workflow for specific bug | Single issue |
Quick Analysis
# Run batch analysis on last 24h of errors
python .claude/scripts/analyze_errors.py
# Analyze last 7 days
python .claude/scripts/analyze_errors.py --days 7
# Generate markdown report
python .claude/scripts/analyze_errors.py --reportWhat Gets Captured
The error collector hook captures:
- Tool name (Bash, mcp__memory__search_nodes, etc.)
- Error message (first 500 chars)
- Tool input (command/query that failed)
- Timestamp and session ID
Location: .claude/logs/errors.jsonl
Current Error Rules
Check learned patterns that trigger warnings:
cat .claude/rules/error_rules.json | jq '.rules[] | {id, signature, count: .occurrence_count}'Files
| File | Purpose |
|---|---|
.claude/hooks/posttool/error-collector.sh | Captures errors to JSONL |
.claude/hooks/pretool/bash/error-pattern-warner.sh | Warns before risky commands |
.claude/scripts/analyze_errors.py | Batch pattern analysis |
.claude/rules/error_rules.json | Learned error patterns |
.claude/logs/errors.jsonl | Raw error log |
Common Patterns
Connection Refused / Wrong Port
pattern: ECONNREFUSED|connection refused|ERR_CONNECTION_REFUSED|connect ECONNREFUSED
fix: The port may have changed or the service isn't running.
1. Check services: portless list (if installed)
2. Use named URLs: api.localhost:1355 instead of localhost:PORT
3. Fallback: lsof -iTCP -sTCP:LISTEN -nP | grep -E 'node|python|java'
4. Install Portless to avoid port guessing: npm i -g portless
pattern: ERR_CONNECTION_RESET|ECONNRESET|socket hang up
fix: Service may have crashed. Check process logs, restart the service,
and use agent-browser to verify the app is responding:
agent-browser open "http://myapp.localhost:1355"PostgreSQL Connection Errors
pattern: role "X" does not exist
fix: Use Docker connection: docker exec -it orchestkit-postgres-dev psql -U orchestkit_user -d orchestkit_dev
pattern: relation "X" does not exist
fix: Check MCP postgres server connection string - may be connected to wrong databaseRelated Skills
ork:fix-issue: Fix identified errorsdebug-investigator: Debug error root causes
Adding New Rules
Rules are auto-generated by analyze_errors.py when patterns repeat 2+ times. For manual rules, edit .claude/rules/error_rules.json:
{
"id": "custom-001",
"pattern": "your regex pattern",
"signature": "human readable signature",
"tool": "Bash",
"occurrence_count": 1,
"fix_suggestion": "How to fix this"
}