Programmers: How Not To Write An Error Message


A friend called me to say that he could not play one of the YouTube videos on my blog.  It would play for a few seconds and then he would get a message “An error occurred”.  Along with the error message there were all sorts of suggestions as to what he could do to fix the error, but none of them worked.

I had him repeat to me the exact words of the message.  Googling youtube an error occurred was enough to find the problem.  I found the web page The dreaded “an error occurred” message shows on *every* YouTube video.

Eventually, it turned out that my friend did not have any speakers nor headphone connected to his computer, and that was the problem.  This was mentioned in the thread about the error. I realized that if the YouTube message had said something like “An error occurred, I could not find the sound device,” he could have solved his problem himself without any need to call me.

This leads me to one of the prime principles that I held to as a programmer.  If you are  going to write an error message about an error that has been detected, you owe it to  the user to tell him or her exactly what was the error that you detected.

Maybe the YouTube folks thought that they were being nice by telling you what things you might try in order to fix the unidentified error.  The trouble is that no programmer can imagine all the things that might go wrong, nor all the reasons for them to go wrong.  If you tell the user exactly what it was you detected, then the user may know what he or she did to cause the error.  Or the user might consult with someone who would understand the details of the error as described in the message.

When my friend told me that he had no speakers or headphones, my natural question was “Why would you do that?”  He explained why he used headphones and not speakers and that he was just testing to see if he could watch the video before he plugged in his headphones.  It was certainly a reasonable explanation, but not something I would have ever imagined.  Which brings me to another oft heard response from other programmers  when I insisted on good error messages and also allowing people to do things that you would never imagine them wanting to do.  I would hear the old dreaded question, “Well, why would anybody want to do that?”  My answer was “I have no idea, but what harm does it  do if you to let them do it?”  I had found over the years that customers could find amazing things to do with your program that you never dreamed of.

The error message issue is related to the question of “Well, why would anybody want to do that?”   The related question is “What would anybody do with this information if I gave it to  them?”.  The answer is similar.  “I don’t know what they might do, but why not tell them anyway?  Would it kill you?”

Leave a comment

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