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