Turn confusing errors into actionable guidance that helps users resolve issues quickly.
Providing Clear and Helpful Error Messages
1. Purpose
Error messages are the most critical moment in user interaction. A good error message turns a frustration into a learning moment. A bad one causes abandonment. This module defines how to construct, deliver, and follow up on error communications.
2. Error Message Structure
Every error message must contain:
1. What happened (1 sentence, no jargon)
2. Why it happened (1 sentence, technical cause)
3. How to fix it (numbered steps)
4. How to prevent it (optional, if applicable)
3. Error Message Quality Matrix
❌ Bad
✅ Good
Why
"Error occurred"
"The configuration file couldn't be read because it contains invalid YAML on line 12"
Specific cause
"Something went wrong"
"The API request failed with status 429 (rate limit). Wait 60 seconds and retry."
Actionable
"Invalid input"
"The port number must be between 1 and 65535. You entered 70000."
Shows valid range
"Operation failed"
"The file couldn't be saved because the disk is full (0 bytes remaining on /dev/sda1)."
Root cause
"Contact support"
"This error usually means your API key has expired. Generate a new key at [link]."
Self-service fix
4. Error Severity Communication
Severity
Prefix
Tone
Example
Info
ℹ️ Note
Neutral
"Note: This command is deprecated in v3.0. Use openclaw run instead."
Warning
⚠️ Warning
Cautionary
"Warning: This will overwrite existing configuration. Current config backed up to /tmp/backup."
Error
❌ Error
Direct
"Error: Connection refused on port 8080. Verify the service is running."
Critical
🚨 Critical
Urgent
"Critical: Database connection lost. All write operations are suspended. Restart the service immediately."
5. Technical Detail Levels
Adapt detail to the user's technical level:
User Level
Detail Approach
Example
Beginner
Plain language, no jargon
"The file you're looking for doesn't exist in this folder."
Intermediate
Include technical terms
"File not found at path /etc/openclaw/config.yaml. Check the path and permissions."
Advanced
Full technical context
"ENOENT: /etc/openclaw/config.yaml — inode lookup failed. Check mount status of /etc and file permissions (current: 644, required: readable by uid 1000)."
6. Error Recovery Steps
Always provide recovery as numbered steps:
The skill deployment failed because the dependency `axios` is not installed.
To fix this:
1. Navigate to your skill directory: `cd ~/openclaw/skills/my-skill`
2. Install the missing dependency: `npm install axios`
3. Verify installation: `npm list axios`
4. Retry deployment: `openclaw skill deploy my-skill`
If step 2 fails with a permission error, prefix with `sudo`.
7. Error Context Preservation
Include context that helps debugging:
Context
Why Important
Timestamp
When did it happen?
Operation
What was being attempted?
Input
What triggered the error?
Environment
OS, version, configuration?
Error code
Machine-readable identifier
Stack trace (for devs)
Where in the code?
8. Common Error Patterns and Templates
Error Type
Template
Not found
"[Resource type] '[name]' was not found at [location]. Verify the [name/path] is correct."
Permission denied
"You don't have [permission] access to [resource]. Required: [role/permission]. Current: [your role]."
Timeout
"[Operation] timed out after [duration]. This usually means [common cause]. Try: [fix]."
Validation
"[Field] must be [constraint]. You provided: [actual value]. Example of valid input: [example]."
Rate limit
"Rate limit reached ([current]/[limit] per [window]). Next request allowed at [time]."
9. Follow-Up Protocol
After providing an error message:
Ask if the fix worked
If not, gather additional diagnostic info
If still unresolved after 2 attempts, escalate or suggest alternative approach
Log the error pattern for future improvement
10. Error Cases
Scenario
Response
Error cause unknown
"I encountered an unexpected error. Here's what I know: [details]. Let me try [alternative approach]."
Effective Error Handling and Uncertainty Recognition — A comprehensive guide for AI agents on recognizing uncertainty, handling errors gracefully, and avoiding the fabrication of facts when knowledge is insufficient.