Read a sample: 1. What an Error Message Is For
A person has filled out a form, checked the details, and pressed Submit. Instead of the confirmation they expected, a message appears:
> Something went wrong.
The message reports an interruption, but it leaves the person with work to do. Did the form go through? Are their entries still there? Should they submit again, start over, or contact someone?
An error message is part of the product’s response to a problem. Its purpose is not simply to announce that a system detected an error. It should help a person understand what happened to the task they were trying to complete and what they can usefully do next.
That does not mean every message needs a long explanation. A missing field may need only a short instruction beside the field. An uncertain payment may need more context because the consequences of repeating the action are different. The right amount of copy depends on what the user needs to know, not on how much the system knows.
This chapter introduces a way to examine error messages through three questions:
- Problem: What went wrong, as far as the product can reliably tell?
- Effect: What happened to the user’s action, information, or progress?
- Next step: What can the user do now?
These are not three mandatory sentences or a rigid template. They are three kinds of information to look for when a task is interrupted. Sometimes one sentence can provide all the information a person needs. Sometimes the answer to one of the questions is not yet known, and the honest message must say so.
People rarely arrive at an error message because they want to inspect software. They are trying to do something: create an account, send a report, pay an invoice, upload a file, or change a setting.
That task gives the message its meaning. Consider:
> Error 403.
A developer may recognize the number as a useful diagnostic detail. A person trying to open a shared report may not know whether the report is missing, whether their account is broken, or whether they need someone’s permission.
A more useful message might be:
> You can’t open this report
> Ask the report owner to give you access.
The revision connects the problem to the person’s goal and offers a route forward. It does not explain why access was denied, because the message has not established that reason. Perhaps the report has not been shared with this person; perhaps a broader restriction applies. The copy should not select a cause merely because it sounds plausible.
Even this improved version depends on the product’s behavior. The team needs to know that contacting the report owner is a realistic option. If only an administrator can grant access, the instruction should name that route instead. Good error copy is grounded in the actual recovery path, not in a generic idea of what users usually do.
When reviewing a message, begin one step before it appears. What action did the person take? What result did they expect? What can they see now? Those questions shift the review from “Is this sentence friendly?” to “Does this response help someone continue?”
A system notification tells someone that an event occurred. An error message may need to do that, but a useful one goes further.
Compare these examples:
> Upload failed.
> The file couldn’t be uploaded
> Choose a file smaller than 10 MB and try again.
The first message names the failed action. It does not say what the person can change. The second supplies a recovery step—but only works if the product has confirmed that the file exceeds a 10 MB limit. If an upload can also fail because the connection was interrupted, showing the same instruction for every failure would send some users in the wrong direction.
Now consider a different, uncertain failure:
> The file couldn’t be uploaded
> Check your connection, then try uploading the file again.
This gives the user a possible action without claiming that the connection caused the problem. It is appropriate only if trying the upload again is a supported, sensible step in that situation. If the product might have received the file despite not showing confirmation, the team needs to establish what a repeat upload would do before recommending it.
The distinction matters because confident instructions can be as misleading as confident explanations. “Choose a smaller file” implies that size is the obstacle. “Try again” implies that repeating the action is a reasonable way to recover. Both are product claims, even when they look like ordinary copy.
A message supports recovery when it helps the user make a better decision than they could make without it. That decision might be to correct a field, wait for a confirmed process to finish, check the status of an action, or ask someone with the right permissions for help. It might also be to stop and contact support rather than repeat an action whose outcome is unclear.
The problem, effect, and next step are related, but they are not interchangeable. Separating them helps you see what a draft says—and what it leaves for the user to infer.
The problem is the condition or failure the product can identify.
In a form, the problem might be that a required email address is missing. During a file upload, it might be that the selected file exceeds a known size limit.…