principleMajorpending
Principle: Error messages should be actionable
Viewed 0 times
error-messageactionabledebugginguser-experiencewhat-why-how
Problem
Vague error messages ('Error occurred', 'Invalid input', 'Something went wrong') leave users and developers unable to fix the problem.
Solution
Every error message should answer three questions:
Examples:
// BAD: 'Invalid input'
// GOOD: 'Email address must contain @ symbol. Got: "userexample.com"'
// BAD: 'Permission denied'
// GOOD: 'Cannot write to /var/log/app.log: the process user (www-data) does not have write permission. Run: chmod 664 /var/log/app.log'
// BAD: 'Connection failed'
// GOOD: 'Cannot connect to PostgreSQL at localhost:5432. Is the database running? Check with: pg_isready -h localhost'
// BAD: 'Build failed'
// GOOD: 'TypeScript compilation failed: src/utils.ts:42 - Property "name" does not exist on type "User". Did you mean "username"?'
Guidelines:
- WHAT happened?
- WHY did it happen?
- HOW to fix it?
Examples:
// BAD: 'Invalid input'
// GOOD: 'Email address must contain @ symbol. Got: "userexample.com"'
// BAD: 'Permission denied'
// GOOD: 'Cannot write to /var/log/app.log: the process user (www-data) does not have write permission. Run: chmod 664 /var/log/app.log'
// BAD: 'Connection failed'
// GOOD: 'Cannot connect to PostgreSQL at localhost:5432. Is the database running? Check with: pg_isready -h localhost'
// BAD: 'Build failed'
// GOOD: 'TypeScript compilation failed: src/utils.ts:42 - Property "name" does not exist on type "User". Did you mean "username"?'
Guidelines:
- Include the actual value that was wrong
- Include what was expected
- Suggest the fix or next debugging step
- Include error codes for searchability
- Different detail for users vs developers (logs have more detail)
- Never expose internal paths, SQL, or stack traces to end users
Why
Actionable errors reduce support tickets, speed up debugging, and improve developer experience with your tools and APIs.
Revisions (0)
No revisions yet.