TweetFollow Us on Twitter

Dec 01 Cover Story

Volume Number: 17 (2001)
Issue Number: 12
Column Tag: Cover Story

by G.D. Warner

Error Messages: The Good, The Bad, And The Ugly

Writing Error Messages That Don’t Make Your Users Feel Stupid

“You are in error. You are a biological unit. You are imperfect.”

As error messages go, that quote from the original Star Trek episode, “The Changeling” is — well, actually kinda scary, considering what happened in that episode (Nomad, remember? A small robot that destroyed planets for fun — because that planet’s inhabitants were, in Nomad,’s “eyes,” imperfect).

While I’m sure RB developers don’t write error messages like that — and, coupled with REAL Software’s failure to insert a “Smite” command into the IDE makes carrying out the implied threat difficult, at best — I wanted to take this opportunity to run through, as the title says, ‘The Good, The Bad, and The Ugly’ of error messages.

The British magazine, MacFormat (which some would say is the British version of MacAddict, though in fact the reverse is true) has a section devoted to bad error messages, entitled “Silly Things Your Mac Says.” Alas, MacFormat’s web presence (http://www.macformat.co.uk) is not quite as strong as that of MacAddict’s (http://www.macaddict.com), so I’m afraid I can’t refer you to a page to view them all. Sorry abut that!

(Initiate Twilight Zone mode: que creepy music, Dim Rod Serling voice as True:)

Consider, if you will, the typical new computer user. S/he has just enrolled in the Computers For Dummies class at her local community college — using Windows ‘00 (pronounced “uh-oh,” in case you were wondering) as the Training Platform of Choice. Everything goes well in the class that first week (remember, we’re using our imaginations, here), and our new computer user finishes that first week, and goes out and buys her own computer.

And gets her first error message. The horror begins (see Figure 1).


Figure 1. Thanks a Lot (End Twilight Zone mode).

Alan Cooper, in his book About Face: The Essentials of User Interface Design, writes: “This is what all error messages feel like to users… No matter how nicely your error messages are worded, this is how they will be interpreted.”

But what makes a good error message?

The Microsoft Manual of Style, Second Edition, provides pointers for writing error messages:

“When you write error messages, use the passive voice to describe the error, and, if necessary, the third person (refer to ‘he computer’ or ‘the program’). You can also blame the product. Addressing the user directly as ‘you’ may imply that the user caused the problem. Try to make error messages friendly, direct, and helpful.”

Apple’s Aqua Human Interface Guidelines tells us:

“A good alert message states clearly what caused the alert to appear and what the user can do about it. Express everything in the user’s vocabulary.”

This is good advice … but Alan Cooper says it a bit better:

“Don’t make the user look stupid.”

Mr. Cooper later provides another interesting example of how error messages shouldn’t be written, reproduced here as Figure 2:


Figure 2. What the —!?

What would go through your mind if the above error message were to show up on your screen? Probably something similar to what Mr. Cooper wrote:

“Thank you so much for sharing that pithy observation with us. Why didn’t you notify the library? What did you want to notify it about? Why are you telling me? What do I care? Maybe you’d like to comment on what I’m wearing, too? And besides, what am I ‘OK’ing? It is not OK with me that this failure occurred!”

Couldn’t have said it better myself.

To reiterate Apple’s recommendations:

  • Tell the user what happened
  • Tell the user how to fix whatever is wrong
  • Tell the user what happened in their own vocabulary

This last one is particularly important: if your error message says something like “PrntSvrErr in Serial/USB port,” your user is most likely going to be confused by “PrntSvrErr.” Why not simply write “Printer Server Error,” if indeed that’s what it means?

The Good

There aren’t a lot of good examples out there… but I did find a few that come close. Take Figure 3 for example:


Figure 3. Example of a Good Error message.

This error message follows the basic guidelines of a good error message:

It tells the user what’s wrong (more or less)

It offers a fix

It delivers its message in plain language Figure 4, from Apple’s Aqua Human Interface Guidelines gets the job done:


Figure 4. Another Good Error Message.

It tells the user what’s wrong — and why

It offers not one, but two possible fixes

It delivers its message in plain language

The error message shown in Figure 5 seems to have done it correctly:


Figure 5. Another Good Error Message.
  • It tells the user what’s wrong — and why
  • It offers not one, not two, but three possible fixes — and includes a phone number for Tech Support
  • It delivers its message in plain language

By all rights, this should be the best of the best — but my technical writer instincts tell me it’s far too wordy. A user faced with this error message would most likely not bother to read it (“Too much information, too much information!”), then just click OK.

The Bad

It’s far easier to find examples of bad error messages than good ones… and a lot more fun! So here we go. Figure 6 is from an early version of Netscape:


Figure 6. Bad Error, Netscape Style.

In his article “Why You Can’t Run Java,” Mark Hurst said…well, basically he said that this error message might be difficult for most users to understand (yeah… that’s it!).

Another, shall we say, somewhat-less-than-useful error message is shown in Figure 7:


Figure 7. Really Bad Error Message.

I wonder what happened here? — Oh, yeah. “Some sort of error.” Obviously.

You’ve probably seen or heard about the e-mail that circulated some time back with error messages written in Haiku, the ancient Japanese form of poetry. For those of you who don’t know (or dozed off a lot during the poetry section of your English classes), Haiku has only three rules:

Three lines only

First and last lines are to be no more than three syllables

Second line consists of no more than seven syllables

Here’s one:

Three things are certain:
Death, taxes, and lost data.
Guess which has occurred.

I’ve placed the URL in the Reference section so you can read the rest… but if you can’t wait, fire up a computer running the BeOS, load up Be’s web browser, NetPositive, and type in a URL without being connected to a network … and see what you get.

Hopefully, you’ll get something like Figure 8:


Figure 8. NetPositive Haiku.

Uh-oh… I feel inspiration beating me about the head and shoulders!

In NetPositive
It is quite easy to find
Poetic Errors

(Sorry about that.)

Someone who identifies himself as “Johnnie Favorite” or “Happy Mega Fighting Man,” and a former Be employee tells me this feature can be turned off in one of the NetPositive settings.

I’ll get to that … one of these days.

Not to be outdone, a few Apple developers at Dantz have written a few of these (at least for early versions of the Retrospect manual) as shown in Figure 9 (thanks to ResExcellence.com):


Figure 9. Dantz Retrospect’s Haiku Error Message.

The Ugly

Not a lot of screenshots for this category, as some of these are Unix/Linux error messages, passed on by Word of Mouth. My favorite:

Printer on fire. See the Reference section for a link for more info on this one…

A close second, from Linux fsck (the Linux version of “Scandisk”):

“Either there is a bug in fsck or some bonehead (you!) is checking a live filesystem. Please report bugs in fsck to .”

‘Tacit’ writes in comp.lang.basic.realbasic:

“For the worst error messages ever written by God or man, I suggest you take a look at Windows 2000. It has some error messages you absolutely will not believe.

‘Attempt to propogate SUIDs across Active Directory failed with code 1602.’

“In English, this means: ‘You have special permissions set for a user who does not exist.’”

Interesting . . .

This error message uses error codes. Opinions on these are mixed: Some like them, some hate them… but they do have their uses.

Using that error code, a developer can track the number of times a particular error is displayed, compare it to other errors that report error codes, and from there decide which one to fix first.

MT-NewsWatcher uses similar error codes in some of its error messages, as shown in Figure 10:


Figure 10. MT-NewsWatcher Error with Error Code.

Tool Tips, the Balloon Help on the Windows side of things, is also something one needs to be careful of. The tool tip shown in Figure 11 cost a developer his job:


Figure 11. One Way Ticket Out the Door for this developer.

Here’s an interesting one, from Free Java:


Figure 12. Let’s Get Biblical.

I wonder if Free Java has a ‘Smite’ command…? Hmmmm …

And then, of course, there’s these:


Figure 13. Dude! (Welcome).


Figure 14. Dude —! (Okay).


Figure 15. Dude —! (Toast).

While it is true that a skilled linguist could probably differentiate between “Dude—!” as an expression of agreement, and “Dude—!” as a warning message, relying on this ability for your error messages is probably not a good idea … so the less said about the “Dude” family of error messages, the better.

In fact, forget I mentioned it, okay?

Okay. So What?

Good question. How about this quote:

“Nothing says more about what you think of your users than error messages.”

This quote, from Scott Berkun’s article, “The Web Shouldn’t be a Comedy of Errors,” really says it all. If it doesn’t ‘say it all’ to you, he follows up with a discussion of some excellent software engineering ideas on handling errors (see Scott Berkun in the Reference section … and take another look at Figure 11).

Like in one of the Karate Kid movies (“Kid? I’m thirty-five!”), when Mr. Miyagi describes the best way to block a punch by the ‘simple’ method of “No be there when punch arrive,” Scott’s article recommends designing your program so that it has fewer chances for your users to require an error message.

Chuck Martin, a posting to the Tech Writer’s list agrees. “…design, as much as possible, the interface so users can’t make errors, or at least will have a more difficult time making errors.”

For instance, a field that requires numerical input should screen out alphabetical characters, as illustrated in this code snippet (KeyDown event of an Edit field):

Listing 1: ASCII Only, Please

Disables non-numerical keystrokes in an edit field.

Function KeyDown(Key As String) As Boolean
 If (ASC(key) < 48) Or (ASC(key) > 57) Then
  If (ASC(key) = 8) Or ((ASC(key) >= 28) And (Asc(key) <= 31)) Then
   Return False
  Else
   Return True
  End If
 Else
  Return False
 End If
End Function

This kills the need for an error message that reads “Dumbkopf! Numbers ONLY in this field!” or something similar.

Another thing to consider (with some applications, anyway): disabling the ‘Okay’ or ‘Submit’ button until all required fields are filled in. This avoids the “You idiot! You forgot to type in your fax number!” error message — when your user doesn’t have a fax number to enter, and simply hits the Okay button, thinking s/he’s finished entering data.

Robert Heath, another member of the Tech Writer’s list (see the Reference section) says, “My own peeve is messages with exclamation points. ‘You must enter a date!,’ etc.

Wrapping Up

In this article, we’ve taken a look at what makes a good error message, what makes a bad error message, touched on some ‘ugly’ error messages, skimmed the surface of software design methodology, and dipped a metaphorical toe into the waters of user interface design. Hopefully, we’ve all learned something along the way… but there’s only one way to be sure! A quiz. Your question — for the grand prize of a bag of pre-cooked microwave popcorn, mailed to your house by our own managing editor, Jessica Stubblefield (first come, first served, no guarantees on how well cooked the popcorn will be):

If your user is trying to print but can’t, is it better to display an error message that reads —

A. “Failed to initialize printer port [OK},”
B. “Having trouble printing. Ensure the printer is connected to your computer and that the power cord is securely connected and press the ‘Retry’ button. {Retry} {Cancel}”

“Printer on fire! Get out now!! {Okay}”

“DUDE!!! {Okay}”

If you answered A, congratulations! Your users will hate you, and you are well on your way to becoming as infamous as the person that wrote that immortal phrase, “Someone put us the bomb.” Or perhaps the other immortal phrase, “All your base are belong to us.”

If you answered B, congratulations! Your users will love you, and actually pay for your shareware.

If you answered C, congratulations! You’re doomed to a lifetime of answering the telephone support lines for the software you wrote, which caused the printer to catch fire in the first place. Your days will be long (15 hours!) and you’ll only get minimum wage — unlike your fellow tech support-folk, who support applications written by the guy whose error messages read like those in answer B. These guys get more money because their developer gets paid for his software.

If you answered D … um … well, the less said about that the better!

You’re educated
Put away this magazine
And go code something.

Heh.

Bibliography and References

Haiku Error Messages:

“Printer On Fire” Error Messages:

‘Linux FSCK’ Error Message:

Just For Laughs . . .


G.D. Warner is a technical writer, a Web-Dev Ninja-In-Training, and resides in Seattle, where the Shadow of Redmond looms long and large. He can be reached at gdwarner@mac.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Bookends 12.5.8 - Reference management a...
Bookends is a full-featured bibliography/reference and information-management system for students and professionals. Access the power of Bookends directly from Mellel, Nisus Writer Pro, or MS Word (... Read more
Chromium 44.0.2403.125 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 44.0.2403.125: This release contains a number... Read more
iMazing 1.2.2 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Audio Hijack 3.2.0 - Record and enhance...
Audio Hijack (was Audio Hijack Pro) drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio... Read more
FontExplorer X Pro 5.0.1 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Calcbot 1.0.2 - Intelligent calculator a...
Calcbot is an intelligent calculator and unit converter for the rest of us. Featuring an easy-to-read history tape, expression view, intuitive conversion, and much more! Features History Tape -... Read more
MTR 5.0.0.1 - The Mac's oldest and...
MTR (was MacTheRipper)--the Mac's oldest and smartest DVD-backup app--is now updated to version 5.001 MTR -- the complete toolbox, not a one-trick, point-and-click extractor. MTR is intended for... Read more
LibreOffice 4.4.5.2 - Free, open-source...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Adobe Lightroom 6.1.1 - Import, develop,...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
File Juicer 4.41 - Extract images, video...
File Juicer is a drag-and-drop can opener and data archaeologist. Its specialty is to find and extract images, video, audio, or text from files which are hard to open in other ways. It finds and... Read more

Pac-Man Championship Edition DX has brou...
Bandai Namco has released Pac-Man Championship Edition DX on iOS and Android, which features the classic arcade gameplay that we've all grown to love. Pac-Man Championship Edition DX can be enjoyed in much shorter bursts than the arcade versions... | Read more »
Cosmonautica (Games)
Cosmonautica 1.1 Device: iOS Universal Category: Games Price: $6.99, Version: 1.1 (iTunes) Description: Cast off! Are you ready for some hilarious adventures in outer space? | Read more »
Rescue humanity from a Demon horde in An...
Angel Stone is Fincon's follow up to the massively successful Hello Hero and is out now on iOS and Android. You play as a member of The Resistance, a group of mighty human warriors who have risen up in defiance of the Demon horde threatening to... | Read more »
Gallery Doctor (Photography)
Gallery Doctor 1.0 Device: iOS iPhone Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Free up valuable iCloud and iPhone storage with Gallery Doctor, the only iPhone cleaner that automatically identifies the... | Read more »
You Against Me (Games)
You Against Me 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: A simple game… You. Me. Claim, steal, lock, score, win! | Read more »
Yep, it's True - Angry Birds 2 is O...
The not exactly rumors were true and the birds are back. Angry Birds 2 has come to the App Store and the world will... well I suppose it'll still be the same, but now we have more bird-flinging options! [Read more] | Read more »
You Could Design Your Own Card for Chain...
If you've ever wanted to create your own item, weapon, trap, or even monster for Chainsaw Warrior: Lords of the Night, this is your chance. Auroch Digital is currently holding a contest so that fans can fight to the death (not really) to see which... | Read more »
Bitcoin Billionaire is Going Back in Tim...
If you thought you managed to buy everything there is to buy in Bitcoin Billionaire and make all the money, well you though wrong. Those of you who made it far enough might remember investing in time travel - and it looks like that investment is... | Read more »
Domino Drop (Games)
Domino Drop 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Domino Drop is a delightful new puzzle game with dominos and gravity!Learn how to play it in a minute, master it day by day.Your... | Read more »
OPERATION DRACULA (Games)
OPERATION DRACULA 1.0.1 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0.1 (iTunes) Description: 25% off launch sale!!! 'Could prove to be one of the most accurate representations of the Japanese bullet hell shmup... | Read more »

Price Scanner via MacPrices.net

Sale! 13-inch MacBook Pros on sale for $100 o...
B&H Photo has 13″ MacBook Pros on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.5GHz/500GB MacBook Pro: $999.99 save $100 - 13″ 2.7GHz/128GB Retina... Read more
Sale! Save $100 on 13-inch MacBook Airs this...
B&H Photo has the 13″ 1.6GHz/128GB MacBook Air on sale for $899.99 including free shipping plus NY tax only. Their price is $100 off MSRP, and it’s the lowest price available for this model.... Read more
Worldwide Tablet Market Decline Continues, Ap...
The worldwide tablet market declined -7.0% year-over-year in the second quarter of 2015 (2Q15) with shipments totaling 44.7 million units according to preliminary data from the International Data... Read more
TP-LINK TL-PA8030P KIT Powerline Featuring Ho...
Consumer and business networking products provider TP-LINK is now shipping its TL-PA8030P KIT AV1200 3-Port Gigabit Passthrough Powerline Starter Kit that expands your home’s network over its... Read more
Apple refurbished iPad Air 2s available for u...
The Apple Store has Apple Certified Refurbished iPad Air 2s available for up to $140 off the price of new models. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB... Read more
Updated Apple iPad Price Trackers
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers. Read more
Apple refurbished 2014 13-inch 128GB MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ MacBook Airs available starting at $759. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.4GHz/128GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store has Apple Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales. Specialist - Retail Customer Service and Sales. Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Online Store UAT Lead - Apple (Unite...
**Job Summary** The Apple Online Store is a fast paced and ever evolving business environment. The User Acceptance Testing (UAT) lead in this organization is able to Read more
*Apple* MAC Support Services Subject Matter...
Title: Apple MAC Support Services Subject Matter Expert Location: Pleasanton, CA Type of position: Temporary Contract for approximately 6 weeks Tasks The tasks for the Read more
Lead Infrastructure Engineer - *Apple* /Mac P...
…of a team * Requires proven problem solving skills Preferred Additional: * Apple Certified System Administrator (ACSA) * Apple Certified Technical Coordinator (ACTC) Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.