Error Message Improve Workflow
Audit and improve error messages in the codebase to be actionable, clear, and helpful for debugging.
Objective
Improve error messages throughout the codebase to reduce support tickets and speed up debugging.
Environment
- A codebase with error handling code
- A search tool (grep, ripgrep)
- Error message style guide or guidelines
Steps
1. Audit messages
Search the codebase for throw, raise, and error creation to find all error messages.
Expected state: A list of all error messages is compiled.
2. Identify weak messages
Flag messages that are vague, lack context, or do not suggest a fix.
Expected state: A list of messages needing improvement is created.
3. Rewrite messages
Rewrite each weak message to include what went wrong, why, and how to fix it.
Expected state: All weak messages are rewritten to be actionable.
4. Test error paths
Trigger each improved error path to verify the new message is displayed correctly.
Expected state: Improved messages appear in the expected error scenarios.
Decision points
Should messages include error codes?
- Yes, for programmatic handling
- No, keep them human-readable
Include error codes for API errors; keep internal errors human-readable with context.
Expected outcome
All error messages in the codebase are clear, actionable, and helpful for debugging.
Verification
Trigger each error path and confirm the improved message is displayed and contains actionable guidance.
Cleanup
No cleanup needed; improved messages should be committed.
Good errors save debugging time
A good error message tells you what happened, why, and what to do next. “Something went wrong” is never acceptable.
throw new Error(`Invalid config: missing "database.host". Check your .env file and ensure DATABASE_HOST is set.`);Implementation Notes
This workflow provides a structured approach to ensure consistent results across team members and environments.
Common Pitfalls
Skipping verification steps or rushing through the process can lead to incomplete results. Always follow each step in order and verify before proceeding.