Error Messages That Help the Person Reading Them

Most error messages are written in the half a second after the developer realises an error is possible. They say “Something went wrong” or “Error 400” and leave the reader stuck. A little more thought turns them into something useful.

Say what happened, specifically

“Invalid input” could mean anything. “The date must be in the future” tells the person exactly what to change. Name the field, name the rule it broke, and if you can, show the value that failed. The reader should not have to guess which of six fields you mean.

Say whether they can fix it

There are two kinds of error and the reader needs to know which one they are looking at. “You can fix this”: wrong format, missing field, file too large. Tell them what to do. “You cannot fix this”: our server is down, a payment provider timed out. Say so plainly, tell them whether to retry or wait, and give them a way to reach you. The worst message is the one that looks fixable but is not, so the person tries the same thing ten times.

Put it where the problem is

An error about a field belongs next to that field, visible without scrolling. A page-level banner is fine for a page-level failure. Mixing the two, a banner for a field error, forces the reader to hunt.

Drop the blame and the jargon

“You entered an invalid email” is worse than “That does not look like an email address”. “Error: ECONNREFUSED” means nothing to most readers. Keep the technical detail for the logs, where it belongs, and give the person on screen a sentence they can act on.

Log the detail you did not show

The user gets the plain version. Your error tracker gets everything: the stack trace, the request id, the input, the user id. That is how you debug the one that does slip through, and it costs nothing to capture.

One security exception

On sign in, be deliberately vague. “Email or password is incorrect”, never “no account with that email”. Everywhere else, detail helps the reader and leaks nothing worth protecting.

The test

Read your error message as someone who has never seen the code. Do you know what went wrong? Do you know if it is your fault? Do you know what to do next? If any answer is no, the message needs another sentence.

Common questions

Should error messages be friendly or technical?

Clear beats both. Plain language, specific about what happened, and honest about whether the user can fix it or should contact you.

What about security, does a detailed message leak information?

On login, keep it vague on purpose. Everywhere else, more detail helps and leaks nothing. Judge per case.

Where should the error appear?

Next to the thing that caused it. A banner at the top of the page for a field error near the bottom means scrolling and guessing.