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.
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:
- What went wrong? (Specific problem)
- Why does it matter? (Impact or consequence—optional for obvious errors)
- 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.
Writing error messages for your product?
River's AI generates clear, helpful error messages that explain problems and guide users to solutions—reducing frustration and support tickets.
Create Error MessagesAuthentication 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.
Need comprehensive error messaging?
River's AI creates complete error message libraries covering validation, authentication, permissions, network issues, and system errors—all in your brand voice.
Generate Error LibraryConflict 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")
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.