How to Write Error Messages That Help Users Solve Problems

Your user tries to sign in. The form shakes. A red box appears at the top: "Error: Authentication failed." What does that mean? Wrong password? Wrong email? Account suspended? The user tries again with the same password. Same error. They try three more times, then give up and email support.

This error message just created a support ticket, frustrated a user, and potentially lost a customer. All because it didn't explain what went wrong or how to fix it.

Error messages are where products either help users recover gracefully or abandon them in frustration. This guide breaks down how to write error messages that actually solve problems—explaining what happened, why it matters, and exactly what users should do next. You'll learn tone and voice strategies, localization considerations, and how to prevent errors before they happen.

Why Most Error Messages Fail

Bad error messages fall into three categories: too vague, too technical, or too focused on the system instead of the user.

Too vague: "An error occurred." Which error? What should I do about it?

Too technical: "422 Unprocessable Entity: Validation failed on field 'user_email'." Most users don't speak HTTP status codes.

System-focused: "Database connection timeout." That's what broke on your end. What should I do on my end?

Good error messages flip this. They explain the problem in user terms and provide a clear path to resolution.

The Three-Part Structure That Works

Every error message should answer three questions:

1. What went wrong? (Specific problem)
2. Why does it matter? (Impact or consequence—optional for obvious errors)
3. How do I fix it? (Actionable next steps)

Example: Bad vs. Good

Bad:
Error 422: Validation failed

This tells you nothing useful. Which validation? What's wrong? How do I fix it?

Good:
This email is already in use

Try signing in instead, or use a different email to create a new account.

[Sign in] [Try different email]

This version answers all three questions: the email is taken (what), you can't create a duplicate account (why—implied), and here are two ways to proceed (how).

Validation Errors: Guide Users to Correct Input

Validation errors happen when users enter data that doesn't meet requirements. These are the most common errors in any product.

Show Errors Next to the Field

Don't show a generic error at the top of the form. Put the message right next to the field that failed:

Password
[********]
⚠️ Password must be at least 8 characters

Users shouldn't have to hunt for which field caused the error.

Be Specific About Requirements

Bad: Invalid password
Good: Password must be at least 8 characters and include one number

The second one tells users exactly what's wrong and what to do differently.

Show Examples for Format Errors

If there's a specific format required, show an example:

Bad: Invalid phone number
Good: Phone number format: (555) 123-4567

Or:

Bad: Invalid URL
Good: Please enter a complete URL starting with http:// or https://

Required Field Errors

For required fields, explain why if it's not obvious:

Phone number is required
We'll use this to verify your account

This gives context. Users understand it's not arbitrary—you need the phone number for a specific reason.

Authentication Errors: Be Clear About Access Issues

Authentication errors are sensitive. You need to be helpful without compromising security.

Incorrect Password

First attempt:

Incorrect password

Please try again or [reset your password].

Direct, clear, provides alternative.

After multiple failures:

Incorrect password

For security, we've temporarily locked your account.
You can try again in 15 minutes or [reset your password] now.

This explains why they're locked out (security) and when they can try again.

Account Not Found

Bad: Invalid credentials
Good: We don't have an account with this email

Check your spelling or [create a new account].

"Invalid credentials" is ambiguous—wrong email or wrong password? Be specific and offer the obvious next action.

Session Expired

Your session has expired

For security, you've been signed out after 30 minutes of inactivity.
Please sign in again to continue.

[Sign in]

This explains why (security timeout), what happened (signed out), and what to do (sign in again).

Permission Errors: Explain Access Restrictions

Permission errors happen when users try to access something they're not allowed to see.

No Permission

You don't have permission to view this file

This file is private. Ask the owner to share it with you,
or contact your team admin for access.

[Contact admin]

This explains the situation and tells users exactly who can grant access.

Feature Requires Upgrade

This feature requires a Pro plan

Upgrade to Pro to access advanced analytics,
export reports, and unlimited team members.

[See plans] [Maybe later]

Frame this as an opportunity, not a restriction. Show the value of upgrading.

Network Errors: Address Connection Problems

Network errors are tricky because the problem might be on the user's end, your end, or somewhere in between.

No Internet Connection

No internet connection

Check your WiFi or mobile data and try again.
Your changes are saved locally and will sync when you're back online.

[Try again]

This is especially important for apps with offline capability. Reassure users their work is safe.

Request Timeout

Request timed out

This is taking longer than expected. Check your connection and try again.
If the problem continues, [contact support].

[Try again]

Timeout could be their connection or your server. Cover both possibilities.

Server Errors: Apologize and Reassure

When something breaks on your end, apologize and explain what's happening.

Generic Server Error

Something went wrong on our end

We're looking into it. Please try again in a few minutes.
If the problem continues, contact support with error code: XYZ123

[Try again] [Contact support]

Acknowledge it's your fault ("on our end"), provide a timeline ("few minutes"), and include an error code for support.

Planned Maintenance

Service temporarily unavailable

We're performing maintenance and will be back shortly.
Expected return: 2:00 PM EST

[Check status page]

Give users a specific time when they can come back. Link to a status page for updates.

Payment Errors: Handle Money Sensitively

Payment errors are stressful for users. Be clear and reassuring.

Card Declined

Your card was declined

Please check your card details or try a different payment method.
Common issues: insufficient funds, incorrect security code, or expired card.

[Update payment method] [Contact support]

Suggest common causes without accusing them of being broke. Offer alternatives.

Payment Processing Failed

Payment processing failed

We couldn't process your payment. Don't worry—you haven't been charged.
Please try again or use a different payment method.

[Try again] [Change payment method]

Immediately reassure them they weren't charged. This is the first thing users worry about.

Conflict Errors: Resolve State Conflicts

Conflict errors happen when the user's action conflicts with the current state of the system.

Duplicate Email

This email is already in use

An account with this email already exists.
Try [signing in] or use a different email.

Explain the conflict and offer two clear paths forward.

Editing Conflict

Someone else edited this document

[User Name] made changes while you were editing.
Your changes have been saved as a draft.

[View their changes] [Merge changes]

Reassure users their work is safe, explain what happened, and show how to resolve the conflict.

Error Message Principles

Use Plain Language

Avoid technical jargon:

❌ "Authentication failed: Invalid credentials"
✅ "Incorrect email or password"

❌ "422 Unprocessable Entity"
✅ "Please check your information and try again"

Be Specific

Vague errors don't help:

❌ "Invalid input"
✅ "Email address is required"

❌ "An error occurred"
✅ "We couldn't upload your file because it's too large (max 10MB)"

Don't Blame the User

Frame errors neutrally:

❌ "You entered an invalid password"
✅ "Incorrect password"

❌ "Your account has been suspended"
✅ "Your account is currently suspended. [Contact support to resolve]"

Provide Actionable Solutions

Every error should tell users what to do:

❌ "File upload failed"
✅ "File upload failed. Check your connection and [try again]"

❌ "Access denied"
✅ "You need permission to view this. [Request access from owner]"

Apologize for System Errors, Not User Errors

System error (your fault):
Sorry, something went wrong on our end

User error (their input):
Please enter a valid email address (no "sorry")

Tone and Voice in Error Messages

Error message tone matters as much as content. The same information delivered differently can feel helpful or hostile.

Match Your Product's Voice

Professional/Enterprise products:

✅ "Password must include at least one number"
❌ "Oops! Your password needs a number, buddy!"

Formal, direct, efficient. Enterprise users expect professionalism, not personality.

Consumer/Friendly products:

✅ "Let's try that again. Check your email and password."
❌ "Authentication failure: credentials invalid"

Warm, conversational, human. Consumer products can be more relaxed.

Developer tools/Technical products:

✅ "API key is invalid or expired (Code: AUTH_401)"
❌ "Whoopsie! Something's not quite right with your API thingy!"

Precise, technical, includes diagnostic information. Developers want specifics, not dumbed-down explanations.

Be Helpful, Not Condescending

❌ "Obviously, you need to enter a valid email"
✅ "Please enter a valid email address"

❌ "As any user would know..."
✅ "Email format: yourname@company.com"

Never make users feel stupid. If the requirement wasn't obvious, that's a design problem, not a user problem.

Be Clear, Not Cute

When users encounter errors, they want solutions, not entertainment:

❌ "Oopsie-daisy! Something went kerflooey!"
✅ "Something went wrong. Please try again."

❌ "Uh oh, spaghetti-o!"
✅ "We couldn't process your request"

Quirky error messages work for brands like Mailchimp or Slack, but only because their entire brand is playful. Match your error tone to your product tone.

Be Direct, Not Wordy

Users scan error messages looking for what to do. Get to the point:

❌ "We regret to inform you that the operation you attempted to perform has unfortunately failed due to circumstances beyond your control"
✅ "This operation failed. Please try again."

❌ "It appears that there may have been an issue with..."
✅ "There was an issue with..."

Be Reassuring, Not Alarming

Even when things go wrong, stay calm:

❌ "CRITICAL ERROR! DATA MAY BE LOST!"
✅ "We couldn't save your changes. Your work is safe—try saving again."

❌ "FATAL: System failure detected"
✅ "Something went wrong on our end. We're looking into it."

Panic doesn't help. Reassurance and clear next steps do.

Avoid Negative Framing When Possible

Positive framing feels more helpful:

❌ "Your trial has ended"
✅ "Upgrade to keep using these features"

❌ "You can't do that"
✅ "This feature requires a Pro plan [Upgrade]"

❌ "You've run out of storage"
✅ "You're at 100% storage. [Upgrade for more space] or [delete old files]"

Focus on what users can do, not what they can't.

Localization and International Considerations

Error messages need to work across languages and cultures.

Write for Translation

Keep messages simple: Complex sentences are harder to translate accurately.

❌ "The password you've entered doesn't meet our security requirements, which, as you may recall from the signup process, include..."
✅ "Password must be at least 8 characters with one number"

Avoid idioms and cultural references:

❌ "You're barking up the wrong tree"
✅ "This email isn't registered"

❌ "No dice" or "Strike out"
✅ "That didn't work"

Idioms don't translate literally and confuse international users.

Use Clear Placeholders

When inserting dynamic content, use clear variable names for translators:

✅ "You've used {current_storage} of {max_storage}"
❌ "You've used {a} of {b}"

Translators need context to position variables correctly in different sentence structures.

Consider Right-to-Left Languages

Text direction affects layout: Error messages with icons or buttons need to work in RTL languages (Arabic, Hebrew).

Test that:

• Icons don't end up on wrong side
• Buttons remain aligned properly
• Line breaks happen appropriately

Date, Time, and Number Formats

Format these according to user's locale:

US: "Rate limit resets at 3:00 PM on 12/31/2025"
Europe: "Rate limit resets at 15:00 on 31/12/2025"
ISO: "Rate limit resets at 15:00 on 2025-12-31"

Use localization libraries—don't hardcode formats.

Length Variations

Translations change message length: German can be 30% longer than English. Design error UI to handle variable text lengths.

Test with:

• Longer languages (German, Finnish)
• Shorter languages (Chinese, Japanese)
• Different character sets (Cyrillic, Asian)

Preventing Errors Before They Happen

Best error message is the one users never see. Prevent errors through better design.

Inline Validation

Show requirements before users submit:

Password
[********]
Must include:
✓ At least 8 characters
✓ One number
✗ One special character

Real-time feedback as they type prevents submission errors.

Constrain Inputs

Make invalid inputs impossible:

• Date picker instead of free text (can't enter invalid date)
• Dropdown instead of text field (can't enter non-existent option)
• Number input with min/max (can't exceed limits)
• File picker with type filter (can't select wrong file type)

Provide Format Examples

Show users what valid input looks like:

Phone number
[____________]
Format: (555) 123-4567

Or use input masks that format automatically:

Credit Card
[1234 5678 9012 3456]
(Automatically adds spaces as user types)

Confirm Destructive Actions

Prevent accidental deletion:

Delete this project?

This will permanently delete "Marketing Campaign 2025"
and all associated files. This cannot be undone.

[Cancel] [Delete Project]

Make destructive button clearly marked (often red) and require second click.

Disable Impossible Actions

Don't let users click things that won't work:

Gray out "Save" button until all required fields are filled. Show why:

[Save] (disabled)
Fill in all required fields to save

Better than letting them click Save and showing an error.

Progressive Disclosure

Show advanced options only when needed:

Simple form by default. "Advanced options" link reveals complex fields. Reduces errors from users accidentally filling things they don't understand.

Smart Defaults

Pre-fill sensible values:

• Current date as default
• Most common option pre-selected
• User's timezone detected automatically
• Currency based on location

Fewer fields to fill = fewer errors.

Testing Your Error Messages

How do you know if your error messages work?

Watch users encounter errors: Do they know what to do next, or do they get stuck?

Check support tickets: If users are emailing support about errors, your error messages aren't clear enough.

Track error recovery rates: After seeing an error, what percentage of users successfully complete their task?

Read them aloud: Do they sound natural and helpful? Or technical and cold?

Common Mistakes to Avoid

Using error codes as the main message: "Error 500" means nothing to users. Put the human explanation first, error code at the end for support reference.

Cute or funny error messages: Humor works in marketing. In errors, users are frustrated—help them, don't entertain them.

All caps or excessive punctuation: "ERROR!!!" feels like yelling. Stay calm and helpful.

Technical stack traces: Never show raw error logs to users. Log them for debugging, show human-readable messages to users.

No way forward: Every error should offer a next action. Don't create dead ends.

Key Takeaways

Error messages should answer three questions: what went wrong (specific problem), why it matters (optional for obvious errors), and how to fix it (actionable steps).

Use plain language that matches how users think, not system-level technical jargon. "Incorrect password" beats "Authentication failed: invalid credentials."

Be specific about problems and solutions. "Email address is required" is better than "Invalid input." Show format examples when requirements aren't obvious.

Apologize for system errors (your fault) but not user errors (their input). "Sorry, something went wrong on our end" vs. "Please enter a valid email address."

Always provide a path forward. Include actionable buttons, links to support, or clear next steps. Never leave users stuck with no way to proceed.

The error messages that work best make users feel helped, not blamed. They reduce frustration, lower support tickets, and turn potential abandonment moments into successful recoveries.

Match tone and voice to your product. Professional products stay formal and direct. Consumer products can be warmer and conversational. Developer tools should be precise and include technical details. Be helpful not condescending, clear not cute, direct not wordy, reassuring not alarming.

Consider localization from the start. Write simple sentences that translate well. Avoid idioms and cultural references. Use clear placeholder names for translators. Test with right-to-left languages. Format dates, times, and numbers according to user's locale. Design UI to handle variable text lengths across languages.

Prevent errors before they happen. Use inline validation showing requirements as users type. Constrain inputs with dropdowns and date pickers. Provide format examples and input masks. Confirm destructive actions. Disable impossible actions until requirements are met. Use progressive disclosure and smart defaults.

Test error messages with real users. Watch them encounter errors—do they know what to do next? Check support tickets for patterns. Track error recovery rates. Read messages aloud to catch awkward phrasing. If users are contacting support about errors, your error messages aren't clear enough.

Most importantly, remember errors are frustration points where users decide whether your product is helpful or hostile. Every error message is an opportunity to build trust by being honest about problems, clear about solutions, and respectful of users' time and intelligence. The products that handle errors gracefully create loyal users who know the product has their back even when things go wrong.