Error Handling Skill
Handle errors intelligently by leveraging past solutions and building a knowledge base of fixes.
Core Workflow
When Encountering an Error
- Recognize the error - Identify the error message and its type
- Search for solutions - Check if a similar error was solved before
- Apply or adapt - Use the found solution or develop a new one
- Log for future - After solving, log the error and solution
Error Recognition
Recognize errors from multiple sources:
| Source |
Indicators |
| Bash commands |
Non-zero exit code, stderr output, error keywords |
| Playwright/Browser |
Console errors, network failures, page crashes |
| Log files |
Error patterns in file content |
| Build output |
Compilation failures, missing dependencies |
| API responses |
HTTP 4xx/5xx status codes, error JSON |
| User messages |
User describes or pastes an error |
Error type keywords to watch for:
- PHP/Laravel:
Fatal error, SQLSTATE, Exception, Class not found
- JavaScript:
TypeError, ReferenceError, Cannot find module
- Python:
Traceback, ImportError, AttributeError
- Database:
Connection refused, Access denied, Table doesn't exist
- Docker:
container is not running, port already allocated
Searching for Solutions
When an error is encountered:
# Search the error memory database
bash $CLAUDE_PLUGIN_ROOT/scripts/search.sh "<error message>" --max 5
Interpret confidence levels:
- 100%: Exact match - apply solution directly
- 70-99%: Very similar - solution likely works, may need minor adaptation
- 50-69%: Related error - review solution for applicability
- 30-49%: Loosely related - use as reference only
Logging New Errors
After solving an error not found in the database:
bash $CLAUDE_PLUGIN_ROOT/scripts/log-error.sh --json '{
"errorMessage": "<full error message>",
"project": "<project name>",
"projectPath": "<working directory>",
"source": "<bash|playwright|read|user|build|api|other>",
"whatHappened": "<what was being done when error occurred>",
"cause": "<root cause of the error>",
"solution": "<how it was fixed>",
"rationale": "<why the solution works>",
"fileChanged": "<optional: file that was modified>",
"codeBefore": "<optional: code before fix>",
"codeAfter": "<optional: code after fix>",
"tags": ["tag1", "tag2"]
}'
Error Source Classification
Classify errors by their origin for better matching:
| Source |
When to Use |
bash |
Errors from shell commands, scripts, CLI tools |
playwright |
Browser errors, page load failures, element not found |
read |
Errors found when reading log files or error outputs |
user |
Errors the user describes or pastes directly |
build |
Compilation errors, asset building failures |
api |
HTTP errors, API response errors |
other |
Anything that doesn't fit above categories |
Tagging Guidelines
Use consistent tags for better searchability:
Technology tags:
- Languages:
php, javascript, python, typescript
- Frameworks:
laravel, react, vue, filament, livewire
- Tools:
docker, composer, npm, git
Domain tags:
database, api, auth, forms, validationrouting, middleware, permissions, migrationstesting, deployment, configuration
Error type tags:
connection, syntax, runtime, type-errormissing-dependency, permission, timeout
Available Commands
| Command |
Purpose |
/error-memory:search <query> |
Search for similar errors |
/error-memory:log |
Log a new error interactively |
/error-memory:list |
List all stored errors |
/error-memory:show <id> |
View full error details |
/error-memory:stats |
View database statistics |
/error-memory:migrate |
Import from old solved-errors.md |
/error-memory:init |
Initialize the database |
Proactive Error Handling
Before Running Commands
If about to run a command that commonly fails:
- Consider what errors might occur
- Have error handling ready (try/catch, error codes)
- Know where to look for solutions
After Errors Occur
- Don't immediately retry the same thing
- Search for the error first
- Understand the cause before applying a fix
- Verify the fix actually resolved the issue
- Log the solution for future reference
Recognizing Patterns
Watch for recurring error patterns:
- Same error type across projects → systemic issue
- Same project with multiple errors → architectural problem
- Same tag appearing often → skill gap to address
Integration with CLAUDE.md
The error memory system enhances the existing CLAUDE.md instruction to log errors to ~/.claude/solved-errors.md by providing:
- Structured storage instead of markdown
- Intelligent search with fuzzy matching
- Usage tracking and statistics
- Automatic error detection via hooks
The old solved-errors.md can be migrated with /error-memory:migrate.
Additional Resources
For detailed error patterns and matching algorithm:
references/error-patterns.md - Common error patterns by technology
1---2name: error-handling3description: This skill should be used when encountering errors during development, when the user mentions an error, when debugging issues, or when asked to "fix an error", "debug this", "why is this failing", "solve this error". Provides intelligent error recognition, solution lookup from past errors, and error logging for future reference.4---5
6# Error Handling Skill
7
8Handle errors intelligently by leveraging past solutions and building a knowledge base of fixes.
9
10## Core Workflow
11
12### When Encountering an Error
13
141. **Recognize the error** - Identify the error message and its type
152. **Search for solutions** - Check if a similar error was solved before
163. **Apply or adapt** - Use the found solution or develop a new one
174. **Log for future** - After solving, log the error and solution
18
19### Error Recognition
20
21Recognize errors from multiple sources:
22
23| Source | Indicators |
24|--------|------------|
25| Bash commands | Non-zero exit code, stderr output, error keywords |
26| Playwright/Browser | Console errors, network failures, page crashes |
27| Log files | Error patterns in file content |
28| Build output | Compilation failures, missing dependencies |
29| API responses | HTTP 4xx/5xx status codes, error JSON |
30| User messages | User describes or pastes an error |
31
32**Error type keywords to watch for:**
33- PHP/Laravel: `Fatal error`, `SQLSTATE`, `Exception`, `Class not found`
34- JavaScript: `TypeError`, `ReferenceError`, `Cannot find module`
35- Python: `Traceback`, `ImportError`, `AttributeError`
36- Database: `Connection refused`, `Access denied`, `Table doesn't exist`
37- Docker: `container is not running`, `port already allocated`
38
39### Searching for Solutions
40
41When an error is encountered:
42
43```bash
44# Search the error memory database
45bash $CLAUDE_PLUGIN_ROOT/scripts/search.sh "<error message>" --max 5
46```
47
48**Interpret confidence levels:**
49- **100%**: Exact match - apply solution directly
50- **70-99%**: Very similar - solution likely works, may need minor adaptation
51- **50-69%**: Related error - review solution for applicability
52- **30-49%**: Loosely related - use as reference only
53
54### Logging New Errors
55
56After solving an error not found in the database:
57
58```bash
59bash $CLAUDE_PLUGIN_ROOT/scripts/log-error.sh --json '{
60 "errorMessage": "<full error message>",
61 "project": "<project name>",
62 "projectPath": "<working directory>",
63 "source": "<bash|playwright|read|user|build|api|other>",
64 "whatHappened": "<what was being done when error occurred>",
65 "cause": "<root cause of the error>",
66 "solution": "<how it was fixed>",
67 "rationale": "<why the solution works>",
68 "fileChanged": "<optional: file that was modified>",
69 "codeBefore": "<optional: code before fix>",
70 "codeAfter": "<optional: code after fix>",
71 "tags": ["tag1", "tag2"]
72}'
73```
74
75## Error Source Classification
76
77Classify errors by their origin for better matching:
78
79| Source | When to Use |
80|--------|-------------|
81| `bash` | Errors from shell commands, scripts, CLI tools |
82| `playwright` | Browser errors, page load failures, element not found |
83| `read` | Errors found when reading log files or error outputs |
84| `user` | Errors the user describes or pastes directly |
85| `build` | Compilation errors, asset building failures |
86| `api` | HTTP errors, API response errors |
87| `other` | Anything that doesn't fit above categories |
88
89## Tagging Guidelines
90
91Use consistent tags for better searchability:
92
93**Technology tags:**
94- Languages: `php`, `javascript`, `python`, `typescript`
95- Frameworks: `laravel`, `react`, `vue`, `filament`, `livewire`
96- Tools: `docker`, `composer`, `npm`, `git`
97
98**Domain tags:**
99- `database`, `api`, `auth`, `forms`, `validation`
100- `routing`, `middleware`, `permissions`, `migrations`
101- `testing`, `deployment`, `configuration`
102
103**Error type tags:**
104- `connection`, `syntax`, `runtime`, `type-error`
105- `missing-dependency`, `permission`, `timeout`
106
107## Available Commands
108
109| Command | Purpose |
110|---------|---------|
111| `/error-memory:search <query>` | Search for similar errors |
112| `/error-memory:log` | Log a new error interactively |
113| `/error-memory:list` | List all stored errors |
114| `/error-memory:show <id>` | View full error details |
115| `/error-memory:stats` | View database statistics |
116| `/error-memory:migrate` | Import from old solved-errors.md |
117| `/error-memory:init` | Initialize the database |
118
119## Proactive Error Handling
120
121### Before Running Commands
122
123If about to run a command that commonly fails:
1241. Consider what errors might occur
1252. Have error handling ready (try/catch, error codes)
1263. Know where to look for solutions
127
128### After Errors Occur
129
1301. Don't immediately retry the same thing
1312. Search for the error first
1323. Understand the cause before applying a fix
1334. Verify the fix actually resolved the issue
1345. Log the solution for future reference
135
136### Recognizing Patterns
137
138Watch for recurring error patterns:
139- Same error type across projects → systemic issue
140- Same project with multiple errors → architectural problem
141- Same tag appearing often → skill gap to address
142
143## Integration with CLAUDE.md
144
145The error memory system enhances the existing CLAUDE.md instruction to log errors to `~/.claude/solved-errors.md` by providing:
146- Structured storage instead of markdown
147- Intelligent search with fuzzy matching
148- Usage tracking and statistics
149- Automatic error detection via hooks
150
151The old `solved-errors.md` can be migrated with `/error-memory:migrate`.
152
153## Additional Resources
154
155For detailed error patterns and matching algorithm:
156- **`references/error-patterns.md`** - Common error patterns by technology
mwguerra