How detailed should error messages be?

Question

I was wondering what the general consensus on error messages was. How detailed should they be?

I've worked on projects where there was a different error message for entering a number that was too big, too small, had a decimal, was a string, etc. That was quite nice for the user as they knew exactly where things went wrong, but the error handling code started to rival the actual business logic in size, and started to develop some of its own bugs.

On the other side I've worked on a project where you'd get very generic errors such as

COMPILE FAILED REASON 3

Which needless to say was almost entirely useless as reason 3 turned out to mean a link error.

So where is the middle ground? How do I know if I've added descriptive enough error messages? How do I know if the user will be able to understand where they've gone wrong?

Answer 1

There are two possible target audiences for an error message, the user, and the developer.

One should generally have the message target the user.

o what is the cause of the problem.
o why the program can't work around the problem
o what the user can do to work around the problem.
o how to report the problem.

If the problem is to be reported, the report should include as much program context information as possible.

o module name
o function name
o line number
o variables of interest in the general area of the problem
o maybe even a core dump.

Target the correct audience.

Answer 2

You should communicate what happened, and what the user's options are, in as few words as possible. The longer the error message is, the less likely the user is to read it. By the same token, short error messages are cryptic and useless. There's a sweet spot in terms of length, and it's different for every situation.

Too short:

Invalid input.

Too long:

Please enter a correctly formatted IP address, such as 192.168.0.1. An IP address is a number used to identify your computer on a network.

Just right:

Please enter a valid IP address.

As far as code bloat is concerned, if a little extra code will prevent a user from calling support or getting frustraited, then it's a good investment.

Answer 3

There are two types of error messages: Those that will be seen by the user and those that'll be seen by the programmer.

"How do I know if the user will be able to understand where they've gone wrong?" I'm assuming that those messages are only going to be seen by the user, and not a very technical one, and COMPILE FAILED REASON 3 is not a typical end-user error message. It's something that the programmer will see(the user doesn't usually compile things).

So, if it's the user that'll see it:

1. Provide a short "This is an error message"("Ops! Something went wrong!", etc.)
2. Provide a small generic description of the error ("The site you're trying to connect to seems to be unavailable"/"You don't seem to have enough permissions to perform the XYZ task"/etc.)
3. Add a "Details>>" button, in case your user happens to understand computers well, including detailed information(exception stack trace, error code, etc.)

Finally, provide some simple and understandable commands for the user ("Try again", "Cancel", etc.)

Answer 4

The real question about error messages is if they should even be displayed. A lot of error messages are presented to a user but there is NO WAY for them to correct them.

As long as there is a way to correct the error then give enough information to the user that will allow them to correct it on their own. If they are not able to correct it on their own is there any reason to tell them the technical reason for the crash? No just log it to a file for troubleshooting later.

Answer 5

As detailed as they need to be ;)

I know it sounds like a smart ass answer but so much of this depends on your target audience and the type of error. For errors caused by invalid user entry, you could show them what constitutes a valid entry. For errors that the user can't control, a generic "we're working on it" type message might do.

I agree with Jon B's comments regarding length as well.

Answer 6

Error messages should be detailed, but clear. This can be achieved by combining error messages from multiple levels:

Failed to save the image
Permission denied: /foo.jpg

Here we have two levels. There can be more. First we tell the big picture and then we tell the details. The order is such that first we have the part understood by most and then the part less people understand, but both can still be visible.

Additionally there could be a fix suggestion.

Answer 7

I would err on the side of more detail, but I think you answered your own question. To avoid the bloat in code then provide useful information in the code/error message but you can give more details in the documentation perhaps or with help files or FAQ.

having too little information is worse in my opinion.

If you are using a language with rich introspection or other capabilities, a log witht he line that failed a check would be useful. The user can then forward to tech support or otherwise get detailed information and this is not additional code bloat, but using your own code to provide information.