/errors

name: errors
license: MIT
compatibility: "Claude Code 2.1.251+. 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              # 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"
}