errors

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 session

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
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

# 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 --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 errors
• debug-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"
}