The Error Message
What you say when something breaks, which is when writing matters most.
The problem it solves
Something failed and the person is stuck. Most error messages describe the system's internal state, which is the one thing the user can do nothing about.
A usable error answers three questions in order: what happened, why, and what to do next. Most messages answer the first badly and skip the other two. Write the third one first, because if there is no next step you have a bug report rather than a message.
- 1Say what failed, in terms of the user's action rather than the subsystem.
- 2Give the reason, if you know it and if it changes what they should do.
- 3State the next step as something they can perform, and make it a control where possible.
- 4Preserve their input. Nothing they typed should be lost to a failure they did not cause.
- 5Include a reference code for anything a support agent will need to trace.
Errors that leave people stranded
- Something went wrong
- Error 500: Internal Server Error
- Invalid credentials
- Operation failed. Please try again later
- You do not have permission to perform this action
- Network error
Errors that hand back control
- We could not save your changes. Your text is still here. Try saving again
- Our servers are having trouble. Nothing was charged. Reference 8F2C. Try again, or email support with that code
- That password does not match the account for [email protected]. Reset password
- The export did not finish because the file exceeded 1 GB. Try exporting a single month instead
- Only workspace admins can delete projects. Ask Priya, your admin, or request access
- You appear to be offline. Your draft is saved on this device and will sync when you reconnect
Tone should be flat and factual. Apology inflation reads as insincere by the third occurrence, and humour in an error is a bet that the person is not already angry, which is a bad bet. Avoid blaming the user even when they caused it: You entered an invalid value becomes That value needs to be a number.
Placement decides whether the message is read. Field problems belong beside the field. Page problems belong at the top of the page with focus moved to them. System-wide problems belong in a persistent banner rather than a toast that vanishes in four seconds, because a disappearing message about a broken system is worse than silence.
Worked example
A hypothetical audit
A team greps their codebase for user-facing error strings and finds a few hundred, most written by whoever happened to be there. Sorting them by how often they fire in production shows that a handful account for the bulk of occurrences. Rewriting those few is an afternoon of work with more effect on support volume than a quarter of feature development.
When it fits
- The failure is something the user can act on, even if the action is only to try again later.
- You can distinguish causes well enough to say something more specific than something went wrong.
- There is a place to put the message near the thing that failed.
- The message can carry a reference code that support can actually look up.
When it backfires
- The message exposes internal detail, like a stack trace or a table name, which frightens users and helps attackers.
- It fires as a transient toast for a problem that persists after the toast disappears.
- It blames the user for a system failure, which turns a small annoyance into a complaint.
- It is written to protect the company from admitting a fault, so it says nothing and the person contacts support instead.
Products using it
Stripe
Returns distinct decline reasons and surfaces user-actionable ones separately from generic failures.
GOV.UK
Publishes error message patterns that require naming the problem and the correction in plain language.
Figma
Keeps local edits and shows a persistent connection banner rather than a toast when the session drops.
The psychology under it
The takeaway
Write the next step first; if there is not one, you have a bug to fix rather than a message to write.
Finished the teardown? Bank it and the day counts toward your run.