| name | errors |
| license | MIT |
| compatibility | Claude Code 2.1.76+. Requires memory MCP server. |
| description | Error pattern analysis and troubleshooting for Claude Code sessions. Categorizes errors (network, auth, model, tool, memory, permission) with known resolution patterns, searches memory for prior occurrences, and suggests recovery steps. Delegates to debug-investigator agent for complex root cause analysis. Use when handling errors, fixing failures, or troubleshooting session issues. |
| context | inherit |
| agent | debug-investigator |
| version | 1.0.0 |
| author | OrchestKit |
| tags | ["errors","debugging","troubleshooting","patterns"] |
| user-invocable | false |
| allowed-tools | ["Read","Bash","Grep"] |
| complexity | low |
| persuasion-type | collaborative |
| effort | low |
| model | haiku |
| metadata | {"category":"document-asset-creation","mcp-server":"memory"} |
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 |
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: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 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"
}
