> ## Documentation Index
> Fetch the complete documentation index at: https://content-designer-ux-writing-skill-26.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="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

    <Note>
      Keep validation errors extremely concise. Users are still filling out the form and need quick guidance.
    </Note>
  </Tab>

  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>

  <Tab title="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

    <Tip>
      Always lead with the user benefit, not the technical requirement. Users are more likely to grant permission when they understand the value.
    </Tip>
  </Tab>
</Tabs>

## What to avoid

<Warning>
  These common patterns create frustration and confusion:
</Warning>

* **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

<Accordion title="❌ 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
</Accordion>

<Accordion title="✅ 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
</Accordion>

### Example 2: Form validation

<Accordion title="❌ 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)
</Accordion>

<Accordion title="✅ After">
  "Email must include @"

  **Why it works**:

  * Specific requirement
  * No blame language
  * Only 4 words
  * Tells user exactly what to fix
</Accordion>

### Example 3: File upload

<Accordion title="❌ Before">
  "Error: Upload failed."

  **Problems**:

  * No explanation of why
  * No recovery action
  * Dead end for user
</Accordion>

<Accordion title="✅ 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
</Accordion>

## Writing empathetic errors

<Steps>
  <Step title="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"
  </Step>

  <Step title="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"
  </Step>

  <Step title="Provide actionable next steps">
    Every error should have a clear recovery path.

    * **Good**: "Connection lost. Check your internet and try again."
    * **Avoid**: "Network error"
  </Step>

  <Step title="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."
  </Step>
</Steps>

## Accessibility considerations

<Check>Use `Error:` prefix for screen readers to identify error messages</Check>
<Check>Associate error text with form fields programmatically</Check>
<Check>Don't rely on color alone - include text and icons</Check>
<Check>Keep critical errors under 14 words for 90% comprehension</Check>

## 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

<CardGroup cols={3}>
  <Card title="Templates" icon="file-lines" href="/reference/templates">
    Use the error message template
  </Card>

  <Card title="Voice and tone" icon="comments" href="/concepts/voice-and-tone">
    Adapt errors to your brand voice
  </Card>

  <Card title="Accessibility" icon="universal-access" href="/guides/accessibility">
    Make errors accessible to all users
  </Card>
</CardGroup>