Writing error messages

Write empathetic, clear error messages that help users recover from problems

Error messages are critical moments in the user experience. A good error message explains what went wrong and provides a clear path to recovery.

The pattern

[What failed]. [Why/context]. [What to do].

Every error message should answer three questions:

1. What happened?
2. Why did it happen?
3. What can I do about it?

Error message types

Validation errors

Validation errors (inline)

Show as user completes a field or on blur. Provide brief, specific guidance to correct input.

Pattern: [Field] [specific requirement]

Examples:

• “Email must include @”
• “Password must be at least 8 characters”
• “Choose a date in the future”

When to show: Real-time or on field exit

Where to show: Below or beside the field

Keep validation errors extremely concise. Users are still filling out the form and need quick guidance.

System errors

System errors (modal/banner)

Show when backend operations fail. Explain what happened and why, then provide a recovery step.

Pattern: [Action failed]. [Likely cause]. [Recovery step].

Examples:

• “Payment failed. Your card was declined. Try a different payment method.”
• “Couldn’t save changes. Connection lost. Reconnect and try again.”
• “Upload failed. File is too large. Choose a file under 10MB.”

When to show: Immediately after failure

Where to show: Modal dialog or prominent banner

Blocking errors

Blocking errors (full-screen)

Prevent continued use until resolved. Provide clear explanation of blocker and resolution.

Pattern: [What's blocked]. [Why]. [Specific action needed].

Examples:

• “Update required. This version is no longer supported. Update now to continue.”
• “Subscription expired. Your account is paused. Renew subscription to restore access.”
• “Verification needed. Confirm your email to access features. Check your inbox.”

When to show: On app launch or feature access

Where to show: Full screen or large modal

Permission errors

Permission errors

Explain the benefit before requesting permission.

Pattern: [User benefit]. [Permission needed].

Examples:

• “Get notified when orders ship. Enable notifications.”
• “Find nearby stores. Allow location access.”
• “Back up your photos. Grant storage permission.”

When to show: When feature is first used

Where to show: In context of the feature

Always lead with the user benefit, not the technical requirement. Users are more likely to grant permission when they understand the value.

What to avoid

These common patterns create frustration and confusion:

• Technical codes without explanation: “Error 403” tells users nothing
• Blame language: “Invalid input” or “illegal character” sounds accusatory
• Robotic tone: “An error has occurred” feels cold and unhelpful
• Dead ends: Error with no recovery path leaves users stuck
• Vague causes: “Something went wrong” doesn’t help users fix the problem

Before and after examples

Example 1: Payment failure

❌ Before

“An error has occurred while processing your payment. Please try again later or contact customer support if the problem persists.”

Problems:

• Passive voice (“has occurred”)
• Vague timeframe (“later”)
• Doesn’t suggest likely cause
• Forces user to escalate immediately

✅ After

“We couldn’t process your payment. Check your card details and try again.”

Why it works:

• Active voice (“we couldn’t”)
• Suggests likely cause (card details)
• Immediate action user can take
• Only 11 words

Example 2: Form validation

❌ Before

“Invalid email address. Please enter a valid email.”

Problems:

• Uses word “invalid” (blame language)
• Doesn’t specify what’s wrong
• Redundant (says “email” twice)

✅ After

“Email must include @”

Why it works:

• Specific requirement
• No blame language
• Only 4 words
• Tells user exactly what to fix

Example 3: File upload

❌ Before

“Error: Upload failed.”

Problems:

• No explanation of why
• No recovery action
• Dead end for user

✅ After

“Upload failed. File is too large. Choose a file under 10MB.”

Why it works:

• Explains what failed
• States the cause
• Provides specific limit
• Clear recovery action

Writing empathetic errors

1. Never blame the user

   Even when the error is user-caused, avoid accusatory language.

   • Good: “Password must be at least 8 characters”
   • Avoid: “You entered an invalid password”
2. Be specific about the problem

   Vague errors create anxiety. Tell users exactly what went wrong.

   • Good: “Your session expired after 30 minutes of inactivity”
   • Avoid: “Session timeout”
3. Provide actionable next steps

   Every error should have a clear recovery path.

   • Good: “Connection lost. Check your internet and try again.”
   • Avoid: “Network error”
4. Match the tone to severity

   High-stakes errors need serious tone. Low-stakes can be lighter.

   • High stakes: “Payment failed. Your card was declined.”
   • Low stakes: “Couldn’t load image. Refresh to try again.”

Accessibility considerations

Use Error: prefix for screen readers to identify error messages

Associate error text with form fields programmatically

Don’t rely on color alone - include text and icons

Keep critical errors under 14 words for 90% comprehension

Quick checklist

Before shipping an error message, verify:

• Explains what failed
• Explains why it failed (when helpful)
• Provides recovery action
• Uses empathetic, non-blaming tone
• Avoids technical jargon
• Works without color (includes text)
• Under 18 words (ideal: 12-15)

Related resources

Templates

Use the error message template

Voice and tone

Adapt errors to your brand voice

Accessibility

Make errors accessible to all users