Writing Error Messages & Troubleshooting Guides That Reduce Support Tickets
By
Mason Goulding
·
Updated
Bad error messages frustrate users and flood your inbox. Good ones turn confusion into self-service. This is the exact framework I use to write errors and troubleshooting that cut support volume in half.
Why most error messages are useless (and expensive)
Vague errors like "Something went wrong" force users to guess — or contact support. Clear, actionable messages let them fix it themselves, saving time and trust.
- Reduce tickets: 40–70% drop when errors are self-explanatory
- Improve UX: users feel in control, not helpless
- SEO side benefit: troubleshooting pages rank for common failure queries
- Developer velocity: consistent patterns speed debugging
My Error & Troubleshooting Stack (2026)
Structured, consistent, and developer-friendly. Focus on frontend clarity + backend logging.
| Layer | Tool | Purpose |
|---|---|---|
| Frontend errors | Custom toast / modal + error codes | User-facing clarity (no dev console needed) |
| Backend logging | Winston / Pino + Sentry | Structured logs with context, stack traces |
| Troubleshooting pages | Eleventy + Markdown + search | Self-service hub for common issues |
| Error codes | ENUM-style codes (e.g., ERR_INVALID_EMAIL) | Searchable, linkable references |
| Validation | Zod / Yup + custom messages | Precise field-level errors |
Related reads: Understanding Core Web Vitals · All About Headers · Automation for Web Development · Website Compliance 101
Principles for error messages that work
- Be human: "Email already in use" > "Duplicate key violation"
- Be actionable: tell the user exactly what to do next
- Include codes: ERR_ prefix + link to docs
- Log context: user ID, request ID, timestamp
- Empathetic tone: "Sorry about that" beats cold errors
My reusable error message template
{
"error": {
"code": "ERR_INVALID_EMAIL",
"message": "The email address you entered doesn't look right.",
"details": "Please check for typos or use a valid format like name@example.com",
"helpUrl": "https://docs.maelstrom.dev/errors/ERR_INVALID_EMAIL",
"requestId": "req_abc123"
}
}Key takeaways
- Make errors human, actionable, and linkable
- Pair frontend messages with rich backend logs
- Build a central troubleshooting hub in your docs
- Track error frequency — fix the top 5 first
