Writing useful error messages

April 3, 2008

Issue: I need some advice on the proper way of writing application error messages. We have a web based application that is a one-stop shop for procuring travel, dining, shipping, and web conferencing services. The system displays error messages if the user does something wrong, forgets to enter values in fields, and etc. These messages are not pop-up boxes but rather the messages are displayed at the top of the screen/page.

For some error messages, the system displays the field with an error and an action the user should take to correct it within parentheses. So the format is: “Field Name (do this action)”, for example: City (enter a valid city name) and Zip Code (enter a valid zip code)

My advice:

The essence of a good error message—no matter what medium—is threefold. It should tell the user:

  1. What happened.
  2. Why it (may have) happened (i.e., give a reason where possible)
  3. How to fix it.

It’s quite possible to combine some of this information into one sentence or phrase, especially where the cause is obvious. (e.g., “Re-type your password. Passwords must be between 6 and 8 characters and contain at least one number.”)

Error messages for situations where the cause is unknown or could be as a result of a variety of actions are harder to describe (#2 above), but giving #1 and #3 are a good start!

The worst kind of error is one that tells the user nothing and doesn’t help them recover from the error condition.

Also, don’t insult the user or call them stupid… there are many ways developers call users stupid without saying so. For example: “The password is wrong! [OK]”. This sort of error message doesn’t help the user at all, and they feel idiotic for not knowing ‘what the computer wants’. The exclamation mark so beloved by certain developers is like a slap in the face and just adds insult to injury.

In your examples, I’d be concerned about “Enter a valid city name”—what’s one of those? If the system knows what’s valid, then have a drop-down list to select from, otherwise I’d assume it’s a text field and therefore any character would be valid. Be careful of validations on this type of field that exclude numbers—at least one or two towns in central British Columbia, Canada have numbers in their name (e.g., 108 Mile House) and some cities may legitimately use a period or hyphen.

For the valid zip code message, you need to be more explicit. While I understand that 5 digit codes are mostly used in the US, I have seen US zip codes written as 11111-2222 too. Other countries don’t call them zip codes, and you can’t guarantee that every country uses the same character length. So, know your users. In Australia we call them postcodes and they’re 4 digits; in the UK they call them something else and they are 6 (or 7?) characters (letters and numbers with a space after the first two) and in Canada they’re 6 characters (letter and numbers) with a space after the third character.

If your users are exclusively in the US, you could get away with “zip code” as a term and a specific character length; but if you sell the product to clients in other countries be aware that those of us living outside the US get really annoyed when we are restricted from entering information because a developer or tester hasn’t thought through the variations on something simple that you take for granted—such as a zip code. (And don’t get me started on entering a state!!! Even when you select another country, there often isn’t an option for <international> or <other> in the state list and all you get are the US states. Where this is a required field, I leave the site—very angry! And all because nobody thought further than their own backyard.)

I got a little sidetracked here, but I hope you make sure these possibilities are considered too.

See also:


  1. […] Writing useful error messages can be tough. Here are a few useful tips. […]

  2. […] enough about my ranting about useless error messages… What causes these MYOB errors and how do you fix […]

  3. […] feel stupid November 18, 2011 Back in 2008 I wrote a post on writing useful error messages (https://cybertext.wordpress.com/2008/04/03/writing-useful-error-messages/), where I stated: The worst kind of error is one that tells the user nothing and doesn’t help […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: