Skip to content
The Product Guys
All lessons
Craft5 min read

Error Messages That Say What To Do Next

Naming the problem is half the job. The message is only finished when it names the fix.

Brightwater handles payroll for small charities. A finance officer uploads a staff CSV at 4:50pm on a Friday. The screen returns: Import failed. Validation error (code 422). She has no idea which of 61 rows is wrong, what rule was broken, or whether any of the file was saved. She emails support and goes home. The charity's payroll run slips a day.

The message is accurate. It is also useless, because it stops at diagnosis. Nielsen's ninth heuristic has been saying this since 1994.

Error messages should be expressed in plain language (no error codes), precisely indicate the problem, and constructively suggest a solution.
Jakob Nielsen, 10 Usability Heuristics

Four parts, and the one that gets dropped

1What happenedIn terms of their work, not the stacktrace.2Why it happenedThe specific cause, and the specificrow or field if there is one.3What state their data is in nowSaved, partly saved, or gone. Silencehere is what makes people retry andduplicate.4What to do nextA concrete action, ideally a buttonthat does it.
The first three are about the past and are the easy ones to write, because the system already knows them. The fourth requires somebody to have decided what the user should do, which is why it is the one missing from the message you are looking at.

Four parts, and the one everybody drops

The anatomy of a usable error

What happened
In the user's terms. Not Validation error but We couldn't import 3 of 61 rows.
What state things are in now
The most commonly missing part. Did anything save? Is the old data intact? Silence here makes people afraid to retry, which is why they contact support instead.
Why
Specific and located. Rows 12, 40 and 55 have a National Insurance number in the wrong format.
What to do next
An action, ideally a control rather than a sentence. Download the 3 failed rows as a button beats please correct the file and try again.

Errors that end the conversation

  • Import failed. Validation error (code 422).
  • Something went wrong. Please try again later.
  • Invalid input
  • You do not have permission to perform this action.
  • Session expired.

Errors that continue it

  • 58 of 61 rows imported. 3 rows have a National Insurance number in the wrong format (rows 12, 40, 55). [Download the 3 failed rows]
  • We couldn't reach the payments provider. Nothing was charged. We'll retry automatically for 10 minutes, or [Retry now].
  • End date is before start date. Payroll periods need to end after they begin.
  • Only account owners can change bank details. [Ask Dela Mensah to do this] or [Request owner access].
  • You were signed out after 30 minutes. Your draft is saved. [Sign in and come back here]

Work down the right column and notice how much of the improvement is state information. Nothing was charged. Your draft is saved. 58 of 61 rows imported. Those clauses cost nothing to render and they are the difference between a user who retries and a user who escalates.

The fourth row does something else worth copying. A permissions error usually ends with a wall. Naming the person who can help turns a dead end into a next step, and it costs one lookup you have already done to determine the user lacks the permission.

Worked example

Brightwater's Friday, replayed

New behaviour: the import runs in two passes. It validates first, then shows a preview with the 3 bad rows highlighted inline and editable, with a note saying Fix these here or import 58 now and add the rest later. The finance officer corrects the three NI numbers in 90 seconds and runs payroll. Import support tickets fall by roughly two thirds over the quarter, and the biggest single contributor is the partial-success path, not the better wording.

Practical rules

  • Validate as close to the input as possible. A field-level error while typing beats a summary at the top on submit, which beats a server error after a page reload.
  • Never blame the user. Invalid input reads as an accusation. End date is before start date reads as a fact.
  • Keep the error code, but demote it. A small reference line at the bottom helps support without being the headline.
  • If the system caused it, say so plainly and say what you are doing about it. We couldn't reach the provider, we'll retry, is honest. Something went wrong is not.
  • Write the empty and error copy while you write the happy path. Errors written after ship get written by whoever is closest to the exception handler.

One test to apply before merging. Read the message aloud and ask what a competent user would do in the next ten seconds. If the honest answer is open a support chat or try again and hope, the message is unfinished, regardless of how well written the first sentence is.

Quick check

Which missing element most often pushes a user to contact support instead of retrying?

The takeaway

An error message is finished when it says what happened, what state the data is in, and what to do next.

Try this tomorrow

Pull your five most frequent error strings from logs and add the missing state clause to each: what saved, what did not, and whether it is safe to retry.

Answer the check above, then bank the day.

Where this comes from

  • 10 Usability Heuristics for User Interface Design, Jakob Nielsen, NN Group
  • The Design of Everyday Things, Don Norman
  • Don't Make Me Think, Steve Krug

Craft is one of six tracks. These lessons summarise and build on the work above, they do not reproduce it. Buy the books, they are better.