# Error handling (/patterns/error-handling)



Put an error where the person can act on it. Name the failed operation, explain what they can change or retry, and keep their input. A failed request should not erase a completed form.

<PatternIllustration pattern="error-handling" />

## Choose the right location [#choose-the-right-location]

| Error                         | Where to show it                                                 | Example guidance                                                                           |
| ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| One field is invalid          | Beside that field.                                               | “Enter an email address with a domain, such as [ada@example.com](mailto:ada@example.com).” |
| Several fields need attention | Summary at the start of the form and messages beside each field. | “Check the 3 highlighted fields.”                                                          |
| A page-level operation failed | A persistent [Banner](/components/banner) near the operation.    | “The import could not finish. Reconnect the source and try again.”                         |
| Access is unavailable         | At the blocked content or action.                                | Explain which access is needed and how to request it, if available.                        |

These are example messages. Use the actual reason returned by the application when it is safe and useful to show. Keep credentials, private values, and internal diagnostics out of public messages.

## Validation and focus [#validation-and-focus]

Use [Form](/components/form) to associate labels, descriptions, and validation feedback. Mark invalid controls programmatically and connect their messages so assistive technology can read them. Keep the message visible until the person has enough information to correct the issue.

On an unsuccessful submission, move focus to an error summary or the first invalid field when that helps the next action. A background failure should announce its status without taking focus from ongoing work.

## Recovery [#recovery]

Retry the operation with the preserved input. For writes, prevent a retry from creating duplicate records if the earlier request succeeded but its response was lost. If the outcome is uncertain, say that it is being checked before offering another submission.

If the user can continue elsewhere, explain what remains available. Use a [Dialog](/components/dialog) only when an immediate decision is required to proceed.

Check failures caused by validation, lost connectivity, rejected permissions, and interrupted requests. Each should leave a clear next step and an accurate [saving status](/patterns/saving).