---
title: "Crafting Error Messages That Actually Help Users"
description: "Methods for creating error messages that effectively guide users and prevent frustration in digital products are explored."
slug: crafting-useful-error-messages
date: 2025-07-01
tags:
  - UX
  - design
  - development
  - user experience
  - error
---

import ImageZoom from "@components/ImageZoom.astro";
import Note from "@components/Note.astro";

As much as your happy path of your UX journey, error mesages are also curcial part of your UX flow. What's surprising is how little attention they get. We spend countless hours perfecting the happy paths while treating error states as afterthoughts.

I've worked on dozens of web projects over the years, and consistently see the same mistake: beautifully designed interfaces suddenly turning into cryptic dead ends when something goes wrong. It's like building an amazing house but forgetting to install proper exit signs - the moment there's smoke, people don't know which way to run.

Here's my practical approach to crafting error messages that actually help users recover and continue their journey.

## 🔍 Plan Your Error Strategy

Consider your UX journey and think all possible ways things can go wrong. Before writing a single error message, take the time to identify all the potential failure points in your user experience. Including general scenarios like network errors, timeout, server errors, logical errors. This proactive approach prevents cryptic default errors from slipping into production.

I typically start by mapping out these common error scenarios:

- Form validation errors (missing fields, incorrect formats)
- Search queries returning no results
- Server errors and API failures
- Authentication and permission issues
- Network connectivity problems

Generally these can be designed as part of your UX flow. And often best way to "see" it all, in a ux flow chart. The most fun style I loke is seeing actual screens and attaching all possible errors into specific screens. For more complex systems, I create a spreadsheet that tracks each error state, its trigger conditions, and the message I want to display. This becomes especially valuable when working with development teams who might otherwise default to technical jargon. This also acts a good inventory of error messages, when we move on to implementing observability into our systems, like noting analytics events right in this sheet as new columns. Or give each error message a code, that gets reported in the events, or perhaps even shown to user as a reference.

## ✍️ Writing Messages That Actually Help

The way you write error messages directly impacts whether users successfully recover or abandon your product in frustration.

The [Wix-UX team article](https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f) linked below, does have a pretty good visualization that hits the key points I cover in this article:

<ImageZoom
  src="/images/blog/2025/good-error-message.jpg"
  alt="Good Error Message"
/>

I really like this framework and only modification I have to this is, adding a link to your help portal, knowledge base about this error that talks in more depth and solutions. That may not apply for simple errors, but sometimes errors have multiple possuble reasons, and differnt solution paths. A dedicated help article allows making users first error message more concise and give them the most common solution, but if user still can't solve their issue, they can click and learn more about that particular problem.

### Write Like You're Sitting Next to Them

Error messages have a strange way of bringing out the robot in us. We suddenly start writing things like "An error occurred processing your request" or "Invalid input #4."

Instead, imagine you're sitting next to the user when they hit a problem (or, usual mom-test: picture your mom seeing that message). How would you explain what went wrong? What advice would you give them?

| **Instead of this** ❌    | **Write this** ✅                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| Invalid email format      | Please enter a valid email address (i.e: example@domain.com)                                        |
| 404 - Page not found      | We couldn't find the page you're looking for. It might have been moved or deleted.                  |
| Payment processing failed | We couldn't process your payment. Please check your card details or try a different payment method. |
| Connection error          | Looks like you're offline. Please check your internet connection and try again.                     |

### Don't Blame the User

When users encounter an error, they're already frustrated. Making them feel like they've done something wrong only adds to that frustration. Avoid phrases like "you did" or "you didn't" when explaining what went wrong.

Compare these approaches:

> "You entered your email incorrectly."

vs.

> "Please enter a valid email address using the format name@example.com"

The difference is subtle but important. The first makes users feel they're at fault; the second simply guides them toward the solution.

## 🔄 Use Active Voice & Offer Clear Next Steps

One of the simplest ways to improve your error messages is switching to active voice. This clarifies who needs to do what and reduces ambiguity.

Instead of:

> "Your form submission could not be processed."

Try:

> "We couldn't process your form because the file you uploaded is too large. Please upload a file smaller than 5MB and try again."

Every error message should include a clear path forward. This applies whether the error is user-fixable or a system failure.

For errors users can fix:

- Clearly explain what went wrong
- Provide specific instructions for resolving the issue
- Make the solution as frictionless as possible
- Include links to documentation for deeper understanding

For system errors users can't fix:

- Explain what happened in simple terms
- Offer an alternative path to accomplish their goal
- Let them know what happened to any data they've already entered
- Include a link to your documentation explaining more about the issue

I love Stripe's approach to form validation errors. They not only highlight the specific field and explain the issue, but also provide direct links to relevant documentation pages when users need additional context. This self-service approach empowers users to solve problems without contacting support.

Another good example to that is Next.js error messages in CLI:

```
error - ./pages/test.module.scss
To use Next.js built-in Sass support, you first need to install `sass`.
Run `npm i sass` or `yarn add sass` inside your workspace.

Learn more: https://err.sh/next.js/install-sass
Require stack:
- /Users/fatih/test/node_modules/sass-loader/dist/getDefaultSassImplementation.js
- /Users/fatih/test/node_modules/sass-loader/dist/getSassImplementation.js
- /Users/fatih/test/node_modules/sass-loader/dist/index.js
- /Users/fatih/test/node_modules/sass-loader/dist/cjs.js
- /Users/fatih/test/node_modules/loader-runner/lib/loadLoader.js
- /Users/fatih/test/node_modules/loader-runner/lib/LoaderRunner.js
- /Users/fatih/test/node_modules/webpack/lib/NormalModule.js
- /Users/fatih/test/node_modules/webpack/lib/NormalModuleFactory.js
- /Users/fatih/test/node_modules/webpack/lib/Compiler.js
```

## 🙅‍♂️ Avoid Negative Language and ALL CAPS

Error messages aren't the place for negative language or SHOUTING AT USERS. Both can intensify the stress of an already frustrating situation.

When crafting error messages:

- Replace "failed," "invalid," or "wrong" with more neutral alternatives
- Never write in ALL CAPITALS (it's the digital equivalent of yelling)
- Avoid exclamation points! They add unnecessary urgency!!!
- Take responsibility when the system is at fault ("We couldn't process" rather than "Processing failed")

One app I regularly use has an error message that reads "INVALID INPUT - TRY AGAIN" when you make a mistake. Every time I see it, I feel like my computer is shouting at me. Don't be that app.

## Error message shows the real teams behind them

It is also a sign of poor thinking and care in moy opinion. A development or product team should pay attention to any of these little details as they are important part of a digital product. Seeing an error message that is not thought, or sloppy shows the team behind it.

In fact, there are many products that have crafted clever, funny error messages that wins users over. It's like the stories we hear Zappos customer support going beyond and making customers happy. Although find balance when writing error message, because it can distract user from the actual solution, or it has company, branding impact.

## Do Real-time and Inline Validation as Much as You Can

One major improvement I strongly advocate for is using inline validation rather than bombarding users with a list of errors in a single error box/banner/popup after submission. Show errors next to problematic fields as soon as users move to the next field.

I've seen countless forms that dump validation errors at the top of the page after submission. This forces users to scroll up and down, trying to match error messages with fields. It's a frustrating experience that's easily avoidable.

Inline validation has several major benefits:

- Users can fix issues incrementally rather than all at once
- It helps users understand exactly which field has the problem
- It's much more accessible for screen reader users

## Further Read

If you want to explore this topic further, here are some excellent resources that have shaped my thinking:

- [When Life Gives You Lemons, Write Better Error Messages](https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f)
- [Google Developers' Guide to Writing Error Messages](https://developers.google.com/tech-writing/error-messages)
- [Nielsen Norman Group's Error Message Guidelines](https://www.nngroup.com/articles/error-message-guidelines/)
- [UX Writing Hub's Error Message Examples](https://uxwritinghub.com/error-message-examples/)

Have you seen particularly good (or terrible) error message examples lately? I'd love to hear your thoughts!
