Write Clearly

Be Concise Avoid Double Negatives Write for the Target Audience Use Terminology Consistently Format Error Messages to Enhance Readability Set the Right Tone

Be Concise

Cut out unnecessary text and emphasize what’s important.

See Examples by me

❌ The file format provided is not supported. Please upload file(s) in the following format(s) - .png.jpeg.

✅ Unsupported file format. Only .png and .jpeg allowed.

See Examples by Google

❌ Unable to establish connection to the SQL database. [Explanation of how to fix the issue.]

✅ Can't connect to the SQL database. [Explanation of how to fix the issue.]

❌ The resource was not found and cannot be differentiated. What you selected doesn't exist in the cluster. [Explanation of how to find valid resources in the cluster.]

✅ Resource <name> isn't in cluster <name>. [Explanation of how to find valid resources in the cluster.]

Final Notes

Error messages should not become cryptic e.g “Unsupported”

Prioritize active voice as it often clarifies or shortens messages.

Avoid Double Negatives

A double negative is a sentence or phrase that contains two negative words e.g. not, can’t, won’t, no, etc.

See Examples by me

❌ This endpoint does not forbid only GET requests.

✅ This endpoint only accepts GET requests.

See Examples by Google

❌ You cannot not invoke this flag.

✅ You must invoke this flag.

❌ The universal read permission on pathname prevents the operating system from forbidding access.

✅ The universal read permission on pathname enables anyone to read
this file. Giving access to everyone is a security flaw. See hyperlink for details on how to restrict readers.

Write for the Target Audience

Error messages must be tailored towards your expected audience.

‘Request failed: Body cannot contain null values’ would definitely not be understood by a non-tech-savvy audience.

See Examples by Google

Now compare the following two error messages. The first error message contains technical truth, but terms like server, client, farm, and CPU are not going to help most consumers:

Inappropriate for shoppers

A server dropped your client's request because the server farm is running
at 92% CPU capacity. Retry in five minutes.

The second error message is more suitable (and comforting) for a
non-technical audience:

Appropriate for shoppers

So many people are shopping right now that our system can't complete your
purchase. Don't worry--we won't lose your shopping cart. Please retry your
purchase in five minutes.

Use Terminology Consistently

Error messages require consistency in terminology to avoid confusion. If you call something “

See Examples by Me

❌ Server currently unavailable. Data center is currently undergoing an upgrade.

✅ Server currently unavailable. Server is currently undergoing an upgrade.

See Examples by Google

❌ Can't connect to cluster at 127.0.0.1:56. Check whether minikube is running.

✅ Can't connect to minikube at 127.0.0.1:56. Check whether minikube is running.

Format Error Messages to Enhance Readability

The following techniques enhance error message readability:

Link to More Detailed Documentation

This is especially handy when there’s a length extra explanation needed.

See Examples by Google

❌ Post contains unsafe information.

✅ Post contains unsafe information. Learn more about safety
at <link to documentation>.

Use Progressive Disclosure

See an interesting illustration by me

TextField widgets require a Material widget ancestor, but none were located. In material design, most widgets are conceptually “printed” on a sheet of material. To introduce a Material widget, either directly include one or use a widget that contains a material itself.

See how that seemed pretty long and you probably skipped to this line.

Wouldn’t it be better to add a drop-down or some other means for users to learn more while shortening the original message? e.g.

TextField widgets require a Material widget ancestor, but none were located.

(Toggle to see more.)

In material design, most widgets are conceptually "printed" on a
sheet of material. To introduce a Material widget, either directly include
one or use a widget that contains a material itself.

💡

I referenced and modified google’s original example above.

Place Error Messages Close to the Error

See an interesting illustration by me


1: program figure_1;
2: Grade = integer;
3: var
4. print("Hello")
Use ':' instead of '=' when declaring a variable.

What do you think? You may be really smart and easily understood the error message above, but consider the modified version below:


1: program figure_1;
2: Grade = integer; 
---------^ Syntax Error
Use ':' instead of '=' when declaring a variable.
3: var
4. print("Hello")

Which do you prefer? v1 or v2? Why? Imagine learning JavaScript as a newbie and seeing v1 as your error message.

Well I’ll leave that to you 🙂.

Handle font colors carefully

See an interesting illustration by me

Pairing color with bold faces

The argument expects only digits. Therefore, the highlighted part of the supplied value is incorrect: 3728LJ947

Pairing color with extra spaces:

3728 LJ 947

Skipping color completely:


3728LJ947
    ^^

Note: Each of them has same prior message as the first one.

Now compare all the above to this:

The argument expects only digits. Therefore, the highlighted part of the supplied value is incorrect: 3728LJ947

If a user is color blind, the little red tint is pretty much invisible to him. That’s why relying solely on color for highlights is not a good idea.

Set the Right Tone

Be Positive

Tell the user how to get it right instead of telling them what they did wrong.

See Examples By Google

❌You entered an invalid postal code.

✅ Enter a valid postal code. [Explanation of valid postal code.]

Don’t be Overly Apologetic

Focus on clearly describing the problem and solution, instead of being overly apologetic. It can be perceived differently depending on user’s culture.

See Examples By Google

❌ We're sorry, a server error occurred and we're temporarily unable
to load your spreadsheet.We apologize for the inconvenience. Please wait a while and try again.

✅ Google Docs is temporarily unable to open your spreadsheet. In the meantime, try right-clicking the spreadsheet in the doc list to download it.

Avoid Humor

Do not mix humor with error messages. Humor often doesn’t cross borders well.

See Examples By Google

❌ Is the server running? Better go catch it :D.

✅ The server is temporarily unavailable. Try again in a few minutes.

Don't blame the user

Customer is always right. Focus the error message on the problem rather than blaming the user.

See Examples By me

❌ You entered a name that is less than 5 characters.

✅ Name must be more than 5 characters.

See Examples By Google