errors

# Error Pattern Analysis Analyze errors captured from Claude Code sessions to identify patterns and get actionable insights. ## Quick Start ```bash /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 ```bash # 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: ```bash 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`: ```json { "id": "custom-001", "pattern": "your regex pattern", "signature": "human readable signature", "tool": "Bash", "occurrence_count": 1, "fix_suggestion": "How to fix this" } ```