Error Pattern Analysis
Analyze errors captured from Claude Code sessions to identify patterns and get actionable insights.
Quick Start
/errors
/debug
When 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 |
CC 2.1.169+: for errors that survive /clear and restarts, claude --safe-mode boots with every customization disabled (CLAUDE.md/plugins/skills/hooks/MCP) — the one-step test that separates "ork/hook/MCP bug" from "CC bug" before deeper analysis.
Quick Analysis
python .claude/scripts/analyze_errors.py
python .claude/scripts/analyze_errors.py --days 7
python .claude/scripts/analyze_errors.py --report
What 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 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 "https://myapp.localhost"
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 database
Hook Errors (CC 2.1.98)
Since CC 2.1.98, hook errors show the first line of stderr directly in the transcript — no need for --debug:
pattern: hook.*error|hook.*failed|PreToolUse.*error
diagnosis: Read the stderr line shown in the transcript.
1. If path error → check CLAUDE_PLUGIN_ROOT is set
2. If JSON parse error → hook is returning invalid JSON
3. If timeout → hook exceeds 50ms budget (PreToolUse) or 100ms (PostToolUse)
4. If "module not found" → run: cd src/hooks && npm run build
Related 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"
}
