Writing Effective Error Messages in English: Principles and Examples
How to write clear, actionable English error messages for software — with good vs bad examples, vocabulary of error states, and rewrite exercises.
Error messages are the most-read writing in most applications, and the most neglected. Users encounter them at moments of frustration or confusion — the worst possible time for vague, technical, or accusatory language. Writing clear, human error messages is a skill that sits at the intersection of technical writing, UX, and English communication. This guide covers the core principles and gives you concrete before/after rewrites.
The Five Principles of Good Error Messages
1. Be Specific
A good error message tells the user exactly what went wrong. A vague message forces the user to guess.
| Bad | Good |
|---|---|
| ”An error occurred." | "Your session expired. Please sign in again." |
| "Something went wrong." | "We couldn’t save your changes — the server returned a timeout." |
| "Invalid input." | "Your password must be at least 8 characters and include one number.” |
Specificity is not about technical detail — it is about communicating the relevant fact clearly.
2. Be Actionable
Every error message should answer the implicit question: “What do I do now?” If the user reads the message and does not know their next step, the message has failed.
- No clear action: “Request failed.”
- Actionable: “We couldn’t process your request. Please check your internet connection and try again.”
Sometimes the action is “contact support” or “try again later.” That is fine — just say it explicitly.
3. Don’t Blame the User
Blame language is both inaccurate and alienating. Most errors are caused by system limitations, design gaps, or edge cases the developer did not anticipate.
| Blaming | Neutral |
|---|---|
| ”You entered an invalid date." | "Please enter a date in the format DD/MM/YYYY." |
| "You must agree to the terms." | "To continue, please accept the Terms of Service." |
| "You’ve exceeded the limit." | "You’ve reached the maximum of 5 projects on the free plan. Upgrade to add more.” |
Note that the neutral versions are also more specific and actionable — good error messages naturally combine all five principles.
4. Include Recovery Steps
Where possible, tell the user exactly how to fix the problem — not just what the problem is.
- “Your credit card was declined. Please check the card number, expiry date, and billing address, then try again.”
- “This email address is already registered. Sign in instead, or reset your password if you’ve forgotten it.”
- “The file you uploaded is 15 MB. Please reduce it to under 10 MB before uploading.”
Recovery steps convert a dead end into a path forward.
5. Avoid Technical Jargon
Unless the audience is explicitly technical (a developer console, a CLI tool), avoid exposing internal technical language.
| Jargon | Plain English |
|---|---|
| ”HTTP 500 Internal Server Error" | "Something went wrong on our end. Please try again in a moment." |
| "ECONNREFUSED: Connection refused to 127.0.0.1:5432" | "We can’t reach our database right now. Please try again later." |
| "Null reference exception in UserService" | "We couldn’t load your profile. Please refresh the page.” |
Vocabulary of Error States
Different types of errors have different standard English descriptions. Using consistent, recognised vocabulary helps users and developers alike.
| Error State | Technical Code | User-Facing Language |
|---|---|---|
| Not found | 404 | ”We couldn’t find that page.” / “This resource no longer exists.” |
| Unauthorised | 401 | ”Please sign in to continue.” |
| Forbidden | 403 | ”You don’t have permission to access this.” |
| Timeout | 408 / 504 | ”The request took too long. Please try again.” |
| Server error | 500 | ”Something went wrong on our end. We’re looking into it.” |
| Validation error | 422 | ”Please check the highlighted fields and try again.” |
| Rate limited | 429 | ”You’ve made too many requests. Please wait a moment before trying again.” |
| Conflict | 409 | ”This record was modified by someone else. Please refresh and try again.” |
| Gone | 410 | ”This content has been permanently removed.” |
Error Message Rewrites
Here are five real-world bad error messages rewritten using the principles above.
Rewrite 1: Generic server error
Original:
Error 500. Try again later.
Rewritten:
Something went wrong on our end. We’ve been notified and are looking into it. Please try again in a few minutes.
Changes: Named the error in plain language, reassured the user the team is aware, gave a time expectation.
Rewrite 2: File upload failure
Original:
File rejected.
Rewritten:
We couldn’t upload your file. Only JPG, PNG, and PDF files are supported, and the maximum file size is 10 MB. Please check your file and try again.
Changes: Specified the rejection reason, listed valid options, provided recovery action.
Rewrite 3: Login failure
Original:
Invalid credentials. Authentication failed.
Rewritten:
The email or password you entered doesn’t match our records. Please try again, or reset your password if you’ve forgotten it.
Changes: Removed jargon (“credentials”, “authentication”), softened the framing, offered a recovery path.
Rewrite 4: Form validation
Original:
You entered invalid data in field 3.
Rewritten:
Please enter a valid phone number. We accept UK numbers in the format 07XXX XXXXXX or +44 7XXX XXXXXX.
Changes: Named the field in a user-facing way, gave a precise format example.
Rewrite 5: Permission error
Original:
Access denied. You lack the required permissions.
Rewritten:
You don’t have permission to view this page. If you think this is a mistake, contact your account administrator.
Changes: Removed “lack” (slightly blaming), added a recovery path for edge cases.
Writing Error Messages for Different Audiences
The principles above apply broadly, but register varies by context:
- Consumer app (non-technical users): Plain English, friendly tone, minimal jargon, always include recovery steps.
- Developer API / CLI tool: More technical detail is appropriate; include error codes, relevant field names, HTTP methods. Developers want precision.
- Admin dashboard: A middle ground — be specific about what failed, include technical identifiers, but avoid raw stack traces.
Key Takeaways
- Specific, actionable, non-blaming error messages reduce user frustration and support tickets.
- Always answer the question: “What should I do now?”
- Use plain English for consumer-facing messages; reserve technical language for developer-facing contexts.
- Consistency in vocabulary (use the same language for the same error state throughout an app) reduces confusion.
- Error messages are an opportunity to communicate competence and care — use it.
Navigating the Nuances: Error Messages for Non-Native Speakers
Writing effective error messages is a cornerstone of good developer communication. We’ve covered the core principles – clarity, specificity, actionable advice – but let’s address a particularly important consideration for developers whose first language isn’t English: mastering the subtle nuances of professional phrasing and vocabulary when describing problem states. It’s not just about conveying what went wrong; it’s about doing so in a way that minimizes frustration and encourages productive troubleshooting. Many developers, even those with strong technical skills, struggle to translate their native language’s approach to error reporting into clear, concise English. This can lead to messages that are technically accurate but ultimately unhelpful or even confusing for someone trying to understand and fix an issue.
One common pitfall is relying on overly literal translations of technical terms. For instance, a phrase like “Resource unavailable” – which might seem perfectly straightforward in another language – can feel vague and uninformative in English. Consider the context. A user clicking a button that triggers a database query failure needs more than just an indication that “a resource was not available.” The goal is to guide them towards understanding why it wasn’t available. Instead, something like “The server encountered an error while attempting to retrieve data for your request. Please try again later, or contact support if the problem persists.” provides immediate context and suggests potential solutions. Similarly, a code review comment stating “Invalid input” is far less helpful than “The username field must contain at least 6 characters.”
Let’s look at how this might manifest in real-world communication. Imagine you’re reviewing a pull request. A developer writes: “Error: System failed.” You could simply respond with “Fix this.” But, to be more supportive and instructive – especially for someone learning English – you might say, “This message is too vague. Could you provide more detail about the nature of the failure? Specifically, what was happening when the error occurred, and are there any relevant logs or stack traces that could help diagnose the problem?” This approach uses precise vocabulary (“nature of the failure,” “relevant logs,” “stack traces”) – terms commonly encountered in professional software development discussions – to encourage a more detailed explanation. It’s about modeling the kind of feedback you’d expect to receive yourself, and demonstrating an understanding of the troubleshooting process.
Finally, remember that brevity is key, but don’t sacrifice clarity for conciseness. Aim for sentences that are long enough to convey essential information without being overly verbose. Using active voice (“The server encountered an error”) is generally preferable to passive voice (“An error was encountered by the server”) as it’s more direct and easier to understand. When crafting error messages, think about how you would explain the problem to a colleague who’s new to the project – that’s often the best way to ensure your communication is accessible and effective.