How to Write Error Messages: Faster, Stronger, Better

Blame the cat, TV, or the neighbors if you want. The thing is: stuff happens. When it does, you need some way to fix it, pronto. Aren’t I right?

This is where error messages can save you bacon.

No one thinks of writing an error message guide until it’s too late.

So, I’m telling you now, grasshopper: Get cracking on that Error Message Guide before it happens.

Why oh why do I need an Error Message Guide?

Here’s the skinny…

These guidelines will help you write error messages that are easy to update and useful for customers.

If you think about it, error messages are the first line of customer support. If written poorly, error messages increase technical support costs. They also frustrate customers, lose sales, and reflects poorly on your software, app, or website.

Errors are a fact of life in software development.

Every site has 404 errors.

Every software has bugs, known issues, and glitches.

Once we accept that, we can begin to help customers use our software, and help them get around the issues they encounter. If you think of it like that, the issue isn’t the error message it is our attitude to creating error messages.

Ok, let’s assume that we want to create really helpful error message, you know, the type we’d like to see if we got lost on a website, using an app, or trying to fill a form on an application.

What’s the purpose of an error message?

A well-written error message tells you, the user, the following:

What has happened
Why has it occurred
How it impacts you and
What you, the user, can do to prevent it happening again?

The error message must include enough information to solve the problem.

What is an error message?

An error message describes a problem that stop a user or system from completing a task.

What types of error messages are there?

There are four main types:

Errors
Confirmations
Warnings
Notifications.

If a message has different audiences, create separate text for users, administrators, and developers.

Why do we use the word error in error messages?

Isn’t part of the problem the word error? It’s assumed the user made the error. If you think about it, the problem is often the software, for example, it wasn’t designed to accommodate unexpected behavior.

If we see it like this, the error is on the side of the developers. If that’s the case, you don’t want to blame the user just because they entered 05122020 instead of 12052020 when entering a date. I tend to use 0512 whereas maybe you use 1205. Good software anticipates this and, where necessary, provides the direction the user needs.

Error Message Guidelines

Error messages should address the following, though not in this order:

Be constructive: tell me what needs to be done!
Be as specific and precise as possible.
Educate. We only read tech docs as a last resort. Knowing this, write error messages that educate and teach the user how to use the application. Nice examples always help.
Indicate that something has gone wrong, but then help the user understand what to do next.
Offer different levels of messages, some for beginners, others for advanced.
Provide direction. Instead of saying, “none in stock,” tell them how to find out when it’s back in stock. Is there some page, app, or contact number that can help them with this?
Save as much as the user’s work as possible. For example, allow users to correct errors instead of having to start from scratch.
Use a positive tone: avoid condemnation.
Use consistent grammar, terminology, and abbreviations.
Use consistent visual formats and placement.
Use terminology your audience will understand.
Use Plain English – plain in the sense that it is concise, accurate, and avoid any unnecessary words.
Use user-centered phrasing.

Error Message Mistakes To Avoid

Try to avoid the following:

Blame. Maybe the user did the wrong thing, for example, entered text into a field meant for numbers, so technically it is their fault. However, instead of saying this is wrong, bad, or illegal, state that this field only takes numbers and encourage them to try again.
Cryptic numbers. Error message 724 for example means nothing to the user. The developer may know what this means but she should refine the error messages to help the user, not her own team or others debugging the application.
Generic ‘catch-all’ messages. Determine the cause of the error and create an appropriate error message.
Jargon. What does syntax error mean?
Jokes.
Negative phrasing, such as wrong, bad, invalid, and illegal.
Red to indicate an error. Red looks terrible. It sends a warning that something is very wrong. Avoid where possible. There is an exception though. If the user is about to do something that could have DRASTIC consequences, then consider using red, for example, if they are about to format their hard disk and lose all data. Let them know this immediately and make it so obvious they can’t miss the warning sign.
Slang or abbreviations.
The word error in the title bar.
Anthropomorphize. Do not imply that the software has feelings or thoughts.
Terms that may be offensive in certain cultures.

How To Improve Error Messages

Ask yourself: how can I help the user solve their problem as painlessly as possibly?

One problem with most error messages is that while they indicate that an error has occurred, they don’t mention what steps the user should take to a) avoid this happening again and b) resolve the current issue.

Rewrite temporary error messages written during testing. Examples of these might refer to null pointer errors or issues with the class, objects, or interfaces in the code. None of this should be displayed to users when the product is finally released.
Many error message leave the user in a type of limbo unsure what caused the issue and, for example, how to recover data they may have lost if the system crashed.
If possible, create links to FAQ pages where users can learn more, download the necessary patches, or contact support.
Get the technical writer to write and enhance the messages. If you’ve no tech writers on your team, assign them to the person with the best writing skills.

How to Write Error Messages

Create a spreadsheet, for example, using Google Spreadsheets so you can share it online.
Add columns for the error message and the root cause.
Give each error a number so you can track them.
Establish an error message quality-control team.
Find best practices. Share with the team.
Create simple to follow writing guidelines for the error messages. Share examples.
Include error and information messages in the design phase.
Place the messages under source control.
Review messages during the development lifecycle.
Attempt to eliminate the need for messages.
Carry out acceptance tests.
Review and revise messages periodically.

Best Practices

You don’t need to use all of these all of the time, but they’re nice to refer to:

Avoid the word “bad”. Use more descriptive terms to tell the user what is wrong. For example, avoid messages such as “Bad size”. Instead, tell the user what criteria to use when specifying a size.
Avoid the word “please”. It can be interpreted to mean that a required action is optional.
Avoid UPPERCASE text and exclamation points.
Explain the solution to the problem. If it has more than one step, link to a Help page the explains the task in detail.
Insert descriptors before a term to clarify the meaning of the sentence. For example, “Specify ID when Detect is set to No.” should be changed to “Specify the ID parameter if the Detect option is set to No.”
State the problem in plain English. Explain what caused the problem. Use complete sentences.
Use active voice if possible.
Use passive voice to describe the error condition.
Use the Cancel button to stop an operation and close the message box.
Use the Close button to close a message box.
Use the Details button to provide more information about the root cause.
Use the Help button to provide more information about the solution.
Use the present tense to describe the conditions that caused the problem.
Write critical errors to an event log.
Write separate error messages for each known issue.

Microsoft’s Guidelines for Error Messages

When you write messages, follow these guidelines:

Avoid vague wording. Give specific names and locations of the objects involved.
Avoid “please.” It can be interpreted to mean that a required action is optional.
Do not refer to implementation details that are invisible to the user. For example, do not refer to the names of functions or objects in the program.
Avoid phrasing that will seem silly to the user, such as “unexpected error.”
Avoid using placeholder variables in the middle of a message. They are very hard to localize.

Correct

The name of the object file conflicts with that of another program in the project. File name: %s

Works did not find a match for this term.

Incorrect

You have named the object file with the name of another program in the project. File name: %s

The term you typed does not appear in this Works file.

Source: Manual of Style for Technical Publications

Example of IBM Software Error Messages

The following is an example of how IBM writes error messages. Notice the words and phrasing as well as how the alert categories are explained.

Error Message

There is no value specified for the User ID.

Explanation

You must specify a value for the user ID.

Alert Category

Similar events are grouped in categories. The alert category is in the following format:

Severity – device component

Severity is one of the following severity levels:

Critical: A key component in the server is no longer functioning.
Warning: The event might progress to a critical level.
System: The event is the result of a system error or a configuration change.

Sample Oracle Error Messages

The following is an example of how Oracle writes error messages.

Notice the format of the error message:

ORA-00058 – error number for tracking
DB_BLOCK_SIZE must be string to mount this database (not string) – description of error message
Cause: what caused the error to occur
Potential reasons: note the use of the word potential in the following example.
Action: what steps need to be taken

For example:

Cause: The value of the DB_BLOCK_SIZE initialization parameter used to start this database does not match the value used when that database was created.

Potential reasons for this mismatch are:

Mounting the wrong database
Using the wrong initialization parameter file
The value of the db_block_size parameter was changed

Action: For one of the above causes, either:

Mount the correct database

Use the correct initialization parameter file

Correct the value of the DB_BLOCK_SIZE parameter

Sample Microsoft Windows Error Messages

The following is an example of error messages for Microsoft Windows XP:

When you try to install a program that uses the Windows Installer in Microsoft Windows XP, the program does not install, and you may receive an error message that is similar to one of the following error messages:

The Windows Installer service could not be accessed. Contact your support personnel to verify that the Windows Installer service is properly registered.
The Windows Installer service failed to start. Contact your support personnel.

Internal Error

This issue may occur when the Windows Installer files are missing or damaged.

To resolve this issue, use one or more of the following methods in the order that they are listed.

It then describes three different methods to resolve the issue.

Method 1: Reregister the Windows Installer

Quit all Windows programs.
Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
Click Start, click Run, type msiexec /regserver in the Open box, and then click OK.
Restart your computer.

Method 2: Remove the Windows Installer files

Quit all Windows programs.
Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
In Windows Explorer, rename the following files in the %systemroot%System32 folder:
- Msi.dll
- Msihnd.dll
- Msiexec.exe

Note: If you cannot rename these files, try to rename the files at a command prompt. To start a command prompt, click Start, click Run, type cmd in the Open box, and then click OK.

Restart Windows XP.

Method 3: Restart Windows XP in Safe Mode

Restart Windows XP in Safe Mode, and then retry Method 1 and Method 2 in the order that they are listed.

Finally, it provides more information about how to restart Windows XP in Safe Mode, by suggesting you read the following article number to view the article in the Microsoft Knowledge Base: 316434 How to perform advanced clean-boot troubleshooting in Windows XP

Sample Google Chrome Errors Messages and Warnings

The following is an example of error messages from Google Chrome. Note the tone, language, and phrasing.

You might see an error message when a download fails.

It will show up on the download bar at the bottom of your browser screen or in the download page that opens.

Note the use of the phrase ‘show up’ instead of display or appear. Likewise, the use of download in lowercase instead of uppercase.

If something you’re about to download could cause problems, Chrome also warns you.

Common warnings for harmful or unwanted programs

Certain downloads can cause viruses, leak your private data, change your browser and computer settings, or add unwanted extensions or toolbars to your browser.

Chrome warns you of potential issues:

Malicious download warning: You tried downloading malware.

Uncommon download warning: You tried downloading an unfamiliar and potentially dangerous piece of software. You should only download programs from sites you trust.

Unwanted software download warning: You tried downloading a deceptive piece of software. This program, disguised as a helpful download, may actually make unexpected changes to your computer.

Virus detected: Antivirus software detected a virus. Your downloaded file may have a virus and, as a result, the file you attempted to download was removed by the Windows Attachment Manager.

In the above example, note the direct ‘you’ phrasing, the relaxed tone, and the use of may and might to suggest the root cause.

This combination of tone, phrasing, and conciseness is encouraging to the reader as it avoids blame.

You feel whoever write this Help page is on your side.

DOWNLOAD: Error Message Template here.