Error messages

Error message structure

A user typically sees an error message when they attempt to perform an action but cannot continue because something isn’t right.

Make your error messages brief yet descriptive. A useful pattern to follow is to include a description, reason, and resolution:

  • Description: What happened?
    • For example, if the user's login failed.
  • Reason: Why did it happen?
    • For example, if an SSH key doesn't allow auto-login.
  • Resolution: How can it be resolved?
    • For example, a user may need to manually log in to the host.

Combine your description, reason, and resolution with a title to create a strong error message. For example:

  • Description: Login failed
  • Reason: The SSH key for auto-login is either not available, is unauthorized, or is password protected.
  • Resolution: To manually log in to the host, click Log in.

Best practices for writing error messages

Keep these best practices in mind when crafting error messages:

Don’t blame users

A user should never feel like the error is their fault. Avoid language like “You did something wrong.” Depending on your message, you may need to use the passive voice instead of the active voice so that you don't assign blame to the user.

Before
After
You did not provide your authentication credentials.
Authentication credentials weren't provided.

Give users a next step

A user should never feel stuck. If they’re hit with an error, give them the information they need to continue with their task.

Before
After
Your list already has the maximum number of items. You are not able to continue customizing.
Your list has the maximum number of items. To continue customizing, remove an item.

Avoid jargon

Error messages are frustrating enough without technical terms that users might not understand. Avoid jargon and use terms that are familiar to your users.

Before
After
Error code 5959: Outdated version information. Task termination pending.
Your task is outdated. To keep it active, update its version.

Include the right amount of description

Tell your user what is wrong. An error without an explanation can add to their frustration and prevent them from finding a solution.

Before
After
An error occurred. The email cannot be sent.
To send this email, turn on your email permissions in user settings.

However, don’t include too much information. The user doesn’t need to know exactly what is going on behind the scenes. Only give them information about what went wrong and what they can do next.

Before
After
Your information cannot be saved. Our system is currently designed to accommodate 1 record per user. The system memory is unable to store more at this time.
Only 1 record can be saved. To continue, remove one of your records.

Lead with the benefit

When providing users with a resolution, start the sentence with their goal ("the benefit"), followed by what they need to do to continue.

Before
After
Click Log in to manually log in.
To manually log in, click Log in.

404 error pages

A 404 page is an error page that a user lands on when the content they're trying to view either doesn’t exist or can’t be found. 404 pages are named after the type of error they communicate: “Error 404: Not found.”

Write 404 pages with error message best practices in mind: Explain what a 404 error is, define how users can proceed, and provide the tools they need to get there.

Effective 404 pages combine several elements to regroup, redirect, and empower lost users to reach their desired destination or find a new one.

The PatternFly 404 page with added call outs to mark four main elements: Heading, next steps, suggested content, and a link to the home page.
  1. Heading: Communicates what a 404 error is in plain language that users can understand. Avoid including “404” or “404 error” unless it’s clearly defined after: “404: That page no longer exists.” Write 404 headings without end punctuation (no period), unless punctuated page headings align with your brand or product.

  2. Next steps: Defines how users can proceed, typically by inviting them to search the site, explore suggested content, or both. Always write the next steps in full sentences and punctuate accordingly.

  3. Suggested content (optional): Points users toward relevant pages such as onboarding information, reference guides, or FAQs.

  4. Link to home page: Provides a quick and easy way for users to navigate back to your site’s home page.

Best practices for 404 error content

Consider your 404 page as a flight path instead of a dead end. Use clear, informative microcopy to point users in the right direction. To see an example, visit PatternFly’s 404 page.

To create effective 404 pages, follow these best practice guidelines:

  1. Use understandable language. Skip technical jargon by writing your 404 heading in plain and specific terms.

    Before
    After
    Error 404: Not found
    404: That page no longer exists
  2. Avoid exclamations, colloquialisms, and excessive humor. Write 404 headings to be informative and repeatable. When users land on a page more than once, jokes grow stale. Steer clear of extraneous words like “Uh oh!” or “Oops!”.

    Before
    After
    Uh oh, spaghetti-o! We lost that one
    We lost that page
    Oops! We dropped the ball
    We couldn't find that page
    Huh, that's odd...
    That page no longer exists
  3. Avoid assigning blame to the user. If your brand doesn’t use first-person plural (“we”) pronouns, use “that page” or “this page” as your heading's subject instead.

    Before
    After
    Your search came up empty
    We can't find that page
    The page you're trying to reach doesn't exist
    That page no longer exists
  4. Turn error into opportunity. Always provide a link back to your site’s home page, and include supplemental next steps below your heading to encourage users to explore options beyond just going back to where they came from.

    Before
    After
    That page doesn't exist.
    Another page might have what you need, so try searching PatternFly.
  5. Channel your brand voice. Bland, impersonal error messages can be frustrating. Infuse your 404 page content with brand personality to support a more inviting site experience.

    Before
    After
    Error 404: Not found
    Requested URL not found on this server. Please try again.
    404: We couldn't find that page
    Another page might have what you need, so try searching PatternFly.
  6. Write for all audiences. Be mindful of localization. Puns, wordplay, and cultural references may not localize for all users. Prioritize clarity over cleverness.

    Before
    After
    404: Not all who wander are lost...
    But this page is. Search again or find your way back home.
    404: We lost that page
    Let's find you a better one. Try a new search or return home.