How to write user-friendly error messages

Error messages are never fun. However, badly written error messages can be outright disruptive to your users and even damage your brand. At Sketch, we’re determined to rid ourselves of bad error messages with a little planning, teamwork — and some clever UX writing, of course!

Why error messages matter

Error messages have a larger impact on users compared to most other types of copy because:

• You gain the user’s undivided attention which rarely happens at the best of times, so you need to make the best of a bad situation.
• You interrupt your users while they’re working, which can be especially frustrating if the issue isn’t easy to fix and becomes a blocker.
• Users expect you to explain the failure points within the error message, regardless of who is at fault (the software, the user, or a third party).

On a broader level, error messages are good indicators of the general state of polish of a website or app. It only takes one poorly written error message to wreck a user’s experience — and that’s not something they’ll soon forget.

Sending the wrong message with mixed signals

Now, let’s take a look at a few examples of bad error messages and how we can improve them.

Problem vs solution

We’ll kick off with a common inline error that you’ve probably seen before:

The person who wrote the first error message framed it as a problem statement and in an abstract way. This puts the blame on the user and isn’t particularly helpful. Instead, one could simply ask the user to do what you require them to do — which is clear in the second example.

When you’re short on space, dive straight into the solution rather than explain the problem in a roundabout way. Focus on guiding the user, rather than shaming them.

Keep your error messages clear

Next up, here’s an error message from an old operating system:

The first message example does almost everything badly. It’s formal and obtuse — and while pretending to be an illegal hacker might be cool, what are we really trying to tell the user? Instead, we can use the second example.

In other words: the app you’re using just broke, so try turning it off and on again. If that doesn’t work, get in touch with the provider (or select View Details).

Know your audience

Here’s another example, taken from photo editing software:

Looking at the first error message, this was probably written by a developer for another developer. However, most end-users are not interested in enumerated mutations. Even the OK button seems resigned to the mystery of what has actually happened.

The sad truth is that sometimes nobody really knows why something went wrong. Was it a single failure — or a ruinous multi-cluster of doom that we cannot possibly solve? Was the error caused by the user, or was it a rare back-end issue caused by a pesky bug?

If you don’t have an answer, it’s usually best to go with a generic message like the second error message.

Sure, it’s not a satisfactory ending — but it’s an ending that the user understands and can act upon.

Unfriendly error messages are a turn-off

One more example, this time from an online retailer:

While the first error message’s borderline hostile tone does make us chuckle (“We’re warning you! This password is simply unacceptable!”), the users who encountered the error in the wild probably didn’t find it very funny.

We’d recommend something like the second example which takes a friendlier approach.

An incorrect password is a small slip-up that happens to everybody — and it’s usually easy to resolve. Treat it as such. Use a friendly tone and don’t accuse anybody — or over-explain how wrong they are.

Bad words are bugs

So bad error messages are everywhere — we’ll even admit that we still have a few to fix here at Sketch, too. But we’re determined to stamp them out because bad error messages are bugs and we need to fix them.

Show your craft

The first rule in squashing bugs is learning how to recognize them. If you’re a writer, take the time to show your team what bad errors look like — especially to developers. Create a few templates and examples to help others distinguish between decent and badly written errors.

And don’t forget about the folks at QA! With just a little training your friendly QA analyst can be a powerful ally who nabs error edge cases before they inadvertently slip into the wild.

Share the love

Since bad error messages are bugs, it means that everybody in your team can help find and fix them. For example, UX designers should document anticipated error scenarios during design and testing (or better yet, design around the errors before they occur in the first place).

Bad error messages are bugs and we need to fix them.

Meanwhile, developers should share known error scenarios that may crop up in the front or back end. For particularly obscure errors, developers and writers should create errors together. No developer should ever need to write an error message by themselves.

Create a source of truth

If you don’t already have one, you’ll need an error archive — a single source of truth where you store all the error messages that your copy ecosystem accumulates over time.

If you’re lucky you’ll have an integrated CMS that magically extracts and displays your error strings. If not, simply record your errors in a shareable spreadsheet or document. It doesn’t really matter where you put them; just keep them somewhere to avoid duplicating work in case you come across similar (or even the same) error scenarios later.

The error archive should, of course, include the string itself. But it should also hold useful metadata such as a unique ID for easier tracking, a description, category tags and links to related design documents or GitHub issues.

Mending errors is a team effort

Bad error messages are a fact of life that won’t go away anytime soon, but they needn’t be a painful experience — for you or your users. Whether you’re writing up new messages or fixing old ones, remember that you’re fixing bugs that will improve your product. It’s worth the effort.

Happy bug hunting!