# Error messages

How to write error messages that say what happened and what to do next.

Section: content
Docs: https://nebula.kaluza.com/content/error-messages

---

Error messages are some of the most important content in a product. When something goes wrong, the user needs to understand what happened and what to do next. A poor error message leaves them stuck.

The best error message is the one that never appears. Before writing an error message, consider whether the error can be prevented through design: better input constraints, auto-correction, or clearer hints. Only surface an error message when other options are exhausted.

## Structure

Every error message must answer: **what happened + why (if useful) + what to do next**.

**Do:** Date of birth doesn't match. Ask the customer to confirm, then re-enter.
**Don't:** Invalid input.
**Don't:** Oops! Something went wrong.

Include the underlying cause only when it genuinely helps the user resolve the issue. Do not explain system constraints for their own sake.

## Language

**Avoid the word "invalid".** It is jargon that tells the user nothing. Describe what is wrong and what a valid input looks like.

**Do:** Sort code must be 6 digits, for example 12-34-56.
**Don't:** Invalid sort code.

**For errors affecting the user's current task**, lead with the effect, not the technical cause.

**Do:** Couldn't save payment plan
**Don't:** HTTP 500 error

**For multiple errors**, tell the user exactly how many changes are needed and what they are.

**Do:** To save, make 2 changes: Enter a valid MPAN. Add a primary contact.
**Don't:** There are 2 errors on this page.

**For errors without a resolution**, give a concrete action rather than a vague link.

**Do:** Something went wrong. Refresh the page to try again.
**Don't:** Something went wrong. Learn more.

**Use the user's own data where possible.** Specific values reduce the need to cross-reference.

**Do:** Payment of £247.50 on 14 Jan 2025 couldn't be processed. Check the account details and try again.
**Don't:** Payment couldn't be processed.

## Two types of error

### System errors

The platform or a third party failed. Use neutral, impersonal phrasing. Do not imply the user did something wrong.

**Do:** Couldn't load this account. Check your connection or try again.
**Don't:** Account failed to load.

### User errors

The user entered something incorrectly. Use passive voice or neutral framing to avoid sounding accusatory. Describe the problem and what a valid input looks like.

**Do:** Sort code must be 6 digits. For example, 12-34-56.
**Do:** The payment has been declined. Check the card details and try again.
**Don't:** You entered the wrong sort code.

## Tone by severity

Match the tone to the consequence of the error.

| Tone | When to use | Example |
|---|---|---|
| Instructive | Low-consequence, simple fix | `Unable to load this page.` |
| Reassuring | Minor error where the user may be worried | `Servers timed out. Try again, and if the problem persists, contact support.` |
| Supportive | Serious error, data loss, or major action required | `Something went wrong. Your progress has been saved. Contact support if this continues.` |

## Apologies

Do not apologise for minor errors. Overuse makes apologies meaningless and delays the useful information. Reserve `sorry` for serious errors that involve data loss or require significant user action to resolve.

Never use whimsical language: `oops`, `whoops`, `oh no`. These undermine trust and are inappropriate in operational contexts.

## Error codes

Include error codes only if the user can use them to contact support or resolve the issue. Always place the code at the end of the message.

**Do:** This profile is unavailable. Try reloading. (Error code: 10213)
**Don't:** Error 10213. This profile is unavailable.

## Validation errors on forms

Always validate on form submission. Never validate as the user types, it interrupts users who are mid-entry.

When errors appear after submission:
- Show them adjacent to the relevant field, below the label and hint text
- List them in the [ErrorSummaryNotification](/components/notification) at the top of the form, with a link to each field
- Use the same wording in the summary as in the inline error, if the inline error contains a link, omit the link from the summary version

The ErrorSummaryNotification title should remain as `There is a problem`. Consistent wording helps users recognise the error pattern across the platform.

## Two approaches to validation error wording

**Instruction**, tell the user directly what to do. For example: `Enter your first name`

Use when the fix is obvious and the field purpose is clear.

**Description**, describe what is wrong, then what to do. For example: `First name must be 35 characters or fewer`

Use when you need to explain a constraint the user may not have anticipated.

Choose whichever sounds more natural and helpful. Do not mix both approaches in the same message.

## Do and don't

| Don't | Do |
|---|---|
| An error occurred | Your meter read could not be submitted |
| Invalid | Mobile number must be 11 digits |
| You forgot to enter your name | Enter your last name |
| Sorry, something went wrong! | Supply point data unavailable |
| Whoops, please try again | Refresh to try again. If this error persists, contact your team lead. |
| No access to this page, sorry! | You don't have permission to view managed exceptions |
| Please enter a valid email address | Enter a valid email address |
| Error 10213. Profile unavailable. | This profile is unavailable. (Error code: 10213) |

## Related

- [Content guidelines](/content/basics)
- [Notification component](/components/notification)
- [Form guidance](/patterns/forms)