Design Guidelines Update: Exception Message Guidelines

It has become clear to me recently that we could be doing a better job with exception messages.  I took these guidelines from a set that the UE team on the .NET Framework uses.  Love to hear your comments, issues, and suggestions.

7.3.2           Exception Error Messages

*      Do provide rich and meaningful message text targeted at the developer when throwing an exception

Annotation (BradA): Unintelligible, incomplete error messages are the most common reason why users contact support. Error messages that precisely and lucidly describe the problem, the probable causes, and the solutions or workarounds help users understand why the error occurred, how to fix it, and how to avoid it in the future. In addition, all exception strings are localized, which makes it especially important to deliver messages that are clearly stated and complete.

*      Do localize exception messages

Annotation (BradA): Many developers that use the .NET Framework are non-English speaking. We localize our entire documentation set (including the huge API reference).  Localizing the error message helps non-English speakers feel more comfortable on our platform. 

*      Do use grammatically correct exception messages. Make the assumption that code may present the user with the exception message.

Each sentence in a description string of an exception should end in a period. This way code that generically displays an exception message to the user does not have to handle the case where a developer forgot the final period, which is relatively cumbersome and expensive.

            Do provide useful information that helps the user diagnose the problem. For example, rather than using “Bad link,” try “Link target does not exist”

            Do be precise. For example, “Missing file name extension” is better than “File not found.”

            Do describe the problem. For example, “Disk full” is better than “File error.”

            Do use third-person, simple present or past tense, and active voice.

            Do use a neutral tone. For example, change the tone in “Bad input” to “Command is unrecognizable.” to avoid blaming the user.

            Do start with search-relevant words. Use passive voice or more complex construction if necessary. For example, “Log file {0} is full.” is preferable to “{0} log file is full.”

            Do use complete sentences. For example, use “Binding is too long.” rather than “Binding too long.”

*      Do not use exclamation points. Notice the difference between “Command is unrecognizable!!” and simply “Command is unrecognizable.”

*      Do not personify (imply that programs think or feel). For example, “Node parameter cannot use Windows NT protocols.” is better than “Parameter node does not speak any of our protocols.”

*      Do not start with an article or variable. Use searchable words at the beginning instead. For example, “Log file {0} is full.” is preferred to “{0} log file is full” or “The {0} log file is full.”

*      Do not use quote marks for emphasis.

*      Do not provide security sensitive information in an exception message.


Comments (25)

  1. Alan McBee says:

    What I think would be more helpful would be if the exception always carried some kind of identifier (yes, I know it’s a pain to uniqueify those) that allowed me to quickly query on all KB articles, or google for pages that discuss solutions. The uniquer, the better. (Don’t throw a dictionary at me, please.) I’ve spent too many times trying to find the KB article for an error by the text of the error message, only to find the answer in a newsgroup where the error message was misttyped by someone who couldn’t cut&paste the exception message from the dialog box/offending web page.


  2. RichB says:

    Any chance you could encourage the IE team to use this advice too. According to this KB article, a new patch to IE preventing username-prefixed URLs and will display the following error message:

    Invalid syntax error

  3. Pavel Lebedinsky says:

    > Do localize exception messages

    I’m probably in the minority here, but I disagree with that.

    When you talk about "users", do you mean end users, programmers, IT/support people or somebody else?

    For end users, it’s going to be a horrible user experience if you start showing them raw exception messages, translated or not. No matter what the guidelines say, there will always be components that use bad/cryptic messages so the best approach for end user applications is to display their own localized errors for exceptions that the application recognizes, and a generic error dialog for everything else. This dialog could have a "Technical Details…" button that would show things like description and stack trace (which for troubleshooting purposes is just as useful as description, if not more).

    For programmers and other technical people localized messages are mostly an annoyance (I’m not a native English speaker so I have some first hand experience with this). To be able to program in .NET you need to understand things like class names anyway, so it’s very unlikely you will have problems understanding exception messages.

    However when you need to troubleshoot a problem for a user and all you have is a Russian exception message from the user’s computer, it’s very unlikely that MS KB search (or even google) will tell you anything.

    Also, what about situations like remoting where exceptions can be raised by server code and handled by clients who have different language settings?

    May be it would be useful to have something like an optional interface that could be used to extract user-friendly, localized descriptions from an exception object, but I think that forcing all exceptions to be localized is wrong.

  4. Ken Brubaker says:


    I specify the use of identifiers for exceptions in my application architectures. But such a requirement is probably best left at the application/enterprise level rather than the base system level. The only reasonable way to have globally unique error codes would be to use guids, but they would be very difficult to communicate on a support call or KB-type look up.

  5. What about a guideline about allways specifying which resource caused the exception, if any?

    So instead of:

    "File was not found."


    "File ‘c:myfile.txt’ was not found."

    It makes it a lot easier to troubleshoot.

  6. Brad Abrams says:

    Alan — yes an identifier is a good idea, I will pass on the suggestion. Although, Ken’s point may pan out to be the only way..

    Rich — I hear you! I will pass on these guidelines (and your comments) to the IE team..

    Pavel raises a good point — The messages are mainly for developers, do you other developers feel like they want english only messages. The remottingadmin issue is a god one, maybe Alan’s ID plan could help?

    Micael has a good point, *if* you are going to put out a file name putting it in quotes is fine. But I will point out that could cause a security issue by giving out PII (Personally Idenitifable Information) such as user name to untrusted callers

  7. Jason Nadal says:

    In RE: Do not personify (imply that programs think or feel).

    I believe the term you are looking for is anthropomorphize (Although Word does think they’re synonyms). Great list.

    I’d also suggest not showing compiler errors to the user. For example, something like "a connection couldn’t be made to a requested resource" instead of "resource error: object reference not set to an instance of an object".

  8. Jerry Pisk says:

    As for IE refusing to use user name and password in a URL with "Invalid Syntax Error" – not only is the message cryptic, it’s not even true – that syntax is valid as far as URLs go, it’s just that IE decided not to support it.

  9. Ken Brubaker says:


    I have written a framework to support different languages that interops with the event log API the way it wants to (It also supports multiple languages). It would be alot easier to dump that support, frankly. There IS one area where it is important, though.

    I agree that end users should not see the errors: All consumer code oriented exceptions should be translated by the UI layer — another reason to require an identifier. However, internal exceptions have TWO audiences, not just developers. Most internal errors get logged somewhere so that a sysop can look at them. Sometimes it it a coding problem and simply gets passed along to the developers. However some internal errors, i.e. non-consumer code errors, are environmentally driven and is the responibility of the IS admin to fix. These SHOULD be in the language of the installation culture.

  10. I have a question, how was the decision for these 2 classes ctor parameters made…

    Constructor for ArgumentNullException

    public ArgumentNullException( string paramName, string message)

    Constructor for ArgumentException

    public ArgumentException( string message, string paramName)

  11. SBC says:

    Provide extended messages (for certain exception types) –

    for e.g.,

    Also see KB Article: Q12345 or 76543:Info

    (with the numerical code containing the hyperlink as a link label)

  12. Ken Brubaker says:

    For my own reference, I thought I’d compile a quick list of design guidelines added by Brad Abrams, et al.

  13. Thomas Eyde says:

    I had an SMTP mail issue in ASP.NET the other day. Try a search on ‘Transporten kan ikke koble til serveren’ or something like that, actual wording is forgotten. If I had the English equivalent ‘The transport failed to connect to the server’ it would be so much easier. I found it by coincidence when I searched on something else.

    So localized system messages is not very helpful. I am a developer and didn’t understand it, I don’t think any local users would do either. Which comittee thought this was a good idea, anyway?

  14. I was looking at BradA’s blog again today and I saw his annotations for proper exception messages. This