Error messages

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.

Keep these best practices in mind when crafting error messages:

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.

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

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

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

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.

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

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.

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.

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.