On this page
Error messages
How to write error messages that say what happened and what to do next.
These guidelines apply to the error text in Nebula components and the products built with them. 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 should aim to answer:
- What happened
- Why, if useful
- What to do next, if known and not clear from context
Do
Date of birth doesn't match.
Date of birth doesn't match. Ask the customer to confirm, then re-enter.
Don't
Invalid input.
Invalid input. Please try again.
Whether to name the customer in the next step depends on whether your user is on a call, which not every flow guarantees. An instruction to ask will otherwise turn a correction into a call they didn't need to make. Where you can't rely on a live conversation, say what needs to be right rather than who to ask.
Include the underlying cause only when it genuinely helps your user resolve the issue. Do not explain system constraints for their own sake.
Language
Avoid the word 'invalid'. It tells your user nothing. Name the mistake they actually made, and write one message for each way the field can fail rather than one covering all of them. Where the data can't tell the failures apart, say what the field expects instead of guessing which one happened.
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 in the title, 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 an 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
Supply point data unavailable. Refresh to try again.
Don't
Something went wrong. Refresh the page to try again.
Name what failed wherever you can. Something went wrong is a last resort, for when the system genuinely can't say, and it always needs a next step after it.
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 say what the field expects.
Do
Sort code must be 6 digits. For example, 12-34-56.
The payment has been declined. Check the card details and try again.
Don't
You entered the wrong sort code.
You declined the payment.
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.
Do
Payment data unavailable. Refresh to try again.
You don't have permission to view managed exceptions.
Don't
Sorry, something went wrong!
No access to this page, sorry!
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
Validate on submission. Don't surface a correctness error while your user is typing, because it interrupts them mid-entry.
A character counter is the one exception. It reports how much they've typed rather than judging whether it's right, so it can update live. A format mask isn't an exception: it interrupts in exactly the way this rule exists to prevent.
When errors appear after submission:
- Show them adjacent to the relevant field, below the label and hint text
- List them in the ErrorSummaryNotification 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.