No application is perfect. Errors will occur, and users will inevitably encounter them.
When a user attempts to perform an action and encounters an error, they are unable to complete the task as intended. This can be frustrating, especially when it impacts their productivity, disrupts their planning, or delays a project.
That is why I consider error messages an important part of the user experience. A well-written error message does more than explain what went wrong—it helps users understand the problem and guides them toward a solution.
Effective error messages#
Before diving into the structure, let's look at what makes an error message effective.
Consider the following scenario:
The user tries to create an account for a colleague so they can collaborate on a project. After pressing the "Save" button, the user sees the error message "An error has occurred".
This message abruptly ends the user's flow. It doesn't explain why the account couldn't be created, whether any data was saved, or what the user should do next.
The impact of the error#
Not every error has the same impact. Some messages are informational, some are warnings, and others prevent the user from completing their task entirely.
The user should immediately understand how serious the issue is and whether they can continue.
What happened#
An error message must clearly explain what happened.
❌ Bad:
"An error has occurred"
✅ Good:
"Unable to create the user account"
The user immediately understands that the account was not created. Use plain language whenever possible and avoid technical terminology.
Why it happened#
An error message should also explain why the issue occurred.
❌ Bad:
"Unable to create the user account"
✅ Good:
"Unable to create the user account because a user with that email address already exists in your team."
Users need enough context to understand why the action failed.
Guide the user#
Whenever possible, guide users toward a solution. Rather than leaving them at a dead end, explain what actions they can take next.
In UX terminology, we call this making a message actionable.
❌ Bad:
"Unable to create the user account because it already exists."
✅ Good:
"Unable to create the user account because a user with that email address already exists in your team. Resend the invitation, remove the existing user, or contact support to resolve the issue."
Keep it simple#
Besides being clear, specific, and actionable, error messages should also be concise. The longer a message becomes, the less likely users are to read it completely.
Use a neutral tone#
Error messages should be factual and neutral. Avoid language that blames the user.
❌ Bad:
"You entered an invalid email address."
✅ Good:
"The email address is not valid."
Both messages communicate the same information, but the second feels less confrontational.
The audience#
The level of detail in an error message should depend on its audience.
Users#
Use plain language, avoid technical terms, and explain how the issue can be resolved.
"Unable to upload the file because it exceeds the 25 MB size limit. Choose a smaller file and try again."
Administrators and support teams#
Provide enough information to troubleshoot the issue efficiently.
"Unable to upload the file. Request ID: ABCD-1234."
Developers#
Provide detailed information and include error codes that make debugging and reproduction easier.
"UPLOAD-102: File rejected. Maximum size is 25 MB; received 31 MB."
Security considerations#
Error messages should help users solve problems without exposing sensitive information.
Never expose environment variables, stack traces, raw exception messages, or external system responses directly to users.
❌ Bad:
"Unable to create the user account. Response 403: Unpaid license."
✅ Good:
"Unable to create the user account because the user management system is currently unavailable. Contact support and mention error code USER-2606."
Detailed technical information should be logged internally rather than displayed to users.
You should also balance helpfulness and security. Provide enough information to resolve the issue, but avoid revealing details that could help an attacker.
❌ Bad:
"You are not allowed to access this invoice because it belongs to Acme Corp."
✅ Good:
"You are not allowed to access this invoice because it does not belong to your team. Select the correct team or view one of the invoices available to you."
Structure of a proper error message#
We now know that effective error messages should:
- Communicate the impact of the issue (impact)
- Tell the user what happened (clear)
- Explain why it happened
- Explain what the user can do next (actionable)
The formula#
impact + what happened + why it happened + possible next steps
For example:
- Impact: Use 💡 for informational messages (typically blue or gray), ⚠️ for warnings (typically yellow or orange), and ❌ for errors (typically red).
- What happened: "Unable to create the user account."
- Why: "A user with that email address already exists in your team."
- Next step: "Resend the invitation, remove the existing user, or contact support."
This results in:
❌ Unable to create the user account. A user with that email address already exists in your team. Resend the invitation, remove the existing user, or contact support if you need assistance.
Review your error messages#
Before releasing a new feature or application, review every error message using the following checklist:
- Is the impact clear?
- Does it explain what happened?
- Does it explain why the issue occurred?
- Does it guide the user toward the next steps?
- Is the message concise and easy to read?
- Does it expose any security risks?
- Is it consistent with other messages in the application?
Final thoughts#
Error messages are part of the user experience.
When they are clear, specific, and actionable, they help users recover quickly instead of becoming stuck. A well-written error message turns a frustrating moment into an opportunity to build trust, reduce support requests, and help users solve problems independently.