Solid Error Messages

Writing good error messages is an art form. It’s important though because the error messages are often the only communication with the user in an already frustrating situation for said user.

I was on Plaxo earlier and got this error message.

There seems to be a problem. I'll tell you what... let us fix it and this can be our little secret. Please wait 30 seconds and try again.

At first, I was a little annoyed that there was an error. But as I read the message, I was amused. The situation was completely defused and I tried again in 30 seconds. Guess what, it worked.

I’m not “keeping the secret” but I started thinking about it and realized how brilliant it is. Your user doesn’t care what the error was because they are not typically (yes we are anomalies because we, as techies, care) interested in if you are not able to connect to SQL Server, or a service that you’re depending on is down or anything else. They want to know that you didn’t just forget about them and that you’re aware of and working on the issue.

errorMethod '~' of object '~' failed They definitely don’t want you to speak techno-babble with them. One of the all-time failures is the “errorMethod ‘~’ of object ‘~’ failed” error message from VB6.

This not only spoke techno-babble at the user, but it gave no useful information or distinguishing information. And it popped up all the time. This error message told me that the developer had not done the appropriate error handling.

I guess that reminds me that the first thing that you need to do error handling in the first place. There are a lot of really good strategies for this. Personally, I really like to have belts and suspenders type methodology here. I use a combination of solid defensive programming (such as checking nulls) as well as global error handling and local error handling in every path. Down to the routine level is probably not the right choice in every case, but the path level is.

Keys to writing a solid error message

Inform. Let the user know that there was an error and you are aware of it. This is especially true with online or connected applications. It’s important for the user to know that the error didn’t just go into the bit bucket but is actually logged and will be looked at. This is, of course, assuming that it’s a true statement.

Apologize. It’s your fault for allowing the error to happen. I, and your user, don’t care that it was an outside service that caused the failure. I was accessing it from your application and you should have planned for this.

Give directions. Now that the usual flow has been upset, what should the user do next? Should they call someone for help? Should they write a letter? Should they just try it again?

Collect additional information if needed. I like the error collection routines that ask me what I was trying to do. This gives me a chance to talk about the other things that might or might not have contributed. This is not always going to be useful but occasionally this will surprise you.

Think. Very often, the error messages are an afterthought or written by the same devs that are writing the rest of the code. This is only appropriate when the dev has a background in linguistics and communications. You should check and double check every error message.