The Readability of Your Error Messages

Every piece of text on your website is read by someone in a particular mood, and it’s worth asking what that mood is. Your homepage is read by the curious. Your pricing page is read by the interested. Your error messages are read by the frustrated — people who just tried to do something and were told no. This is the worst audience any writer ever faces: annoyed, in a hurry, and primed to blame you. And it’s precisely the audience most sites address in their laziest, most careless prose.

“An error occurred.” “Invalid input.” “Something went wrong.” Consider what these sentences actually accomplish. The user already knows something went wrong; that’s why there’s a red box. So a message that only announces wrongness has an information content of zero. It occupies the exact spot where help was needed and delivers none. It’s like a road sign that says “sign.”

Reading ability degrades under stress, which is a fact worth taking seriously. A person who just had their work rejected by a form is not reading at their best. They skim angrily. They miss words. Whatever grade level you write your marketing at, your error messages need to come in below it, because your reader’s effective level just dropped. This is the strongest version of the write-plainly argument: not that your users are simple, but that at this particular moment, everyone is.

A good error message has to do three jobs in one or two short sentences, and it helps to name them. What happened. Why, if the why is useful. What to do now. “We couldn’t charge your card. The card number doesn’t match a valid card — check it and try again.” Happened, why, do. No message needs more than that, and no message should deliver less. The third job is the one most often skipped, and it’s the one the user actually came for. An error message without a next step is a diagnosis without a prescription.

The classic failure is writing from the system’s point of view instead of the reader’s. Engineers write error messages while looking at code, so the messages describe what the code experienced: “Validation failed,” “Unexpected response,” “Error 422.” These are honest reports from inside the machine, and useless outside it. The user doesn’t share the system’s perspective and shouldn’t have to. A message that says “Request entity too large” and a message that says “That file is too big — the limit is 10 MB” describe the same event. One describes it to the developer, the other to the person holding the file. Note that the second version also quietly answers the follow-up question — how big is too big? — which is the difference between an error message and a dead end.

Tone deserves a paragraph, because two opposite mistakes are both common. The first is blame: “You entered an invalid email.” The word “you” plus the word “invalid” reads as an accusation, and half the time it’s false — the input was fine and the parser was picky. Describing the problem instead of the culprit costs nothing: “That email address doesn’t look complete — it’s missing the part after the @.” The second mistake is forced whimsy: “Whoops! Our hamsters fell off their wheels!” A cute error message is written for the writer’s amusement, not the reader’s situation, and the mismatch grows with the stakes. Nobody who just lost a form full of typed answers wants to hear about hamsters. Calm and plain outlasts clever every time someone’s actually stuck.

Placement is part of readability too, in a way that pure prose people overlook. An error that appears at the top of the page, while the offending field sits three screens down, forces the reader to hold the message in memory while hunting for its subject — on a phone, scrolling, angry. Put the message next to the field it concerns, and make the connection explicit in code as well as in pixels, so screen readers announce the error together with the field. A perfectly written message in the wrong place is still an unreadable one.

The economically interesting thing about error messages is where they occur. Errors cluster at moments of commitment: signup, checkout, upload, submit. These are the moments users are most valuable and most ready to quit. A confusing message at the checkout is not a cosmetic flaw; it’s a leak at the narrowest point of the funnel, invisible in screenshots because screenshots are taken of the happy path. When I audit sites, the error states are reliably the least-written text on the page — first drafts frozen in production for years, shown daily to the people closest to becoming customers.

Here’s the exercise I’d actually recommend. Go break your own site. Type a wrong password, an impossible date, a too-long name; submit an empty form; upload the wrong kind of file. Read every message that appears, out loud, as if to someone leaning over your shoulder asking “so what do I do?” Any message that can’t answer that question fails. You’ll likely find a dozen in an afternoon, and each one costs a sentence to fix. There is no cheaper writing work with a worse-tempered, better-motivated audience waiting on the result.