Writing Error Messages That Help
By Maksym Bardakh · Co-founder & President
In short
An error message reaches the user at a moment of failure, so its job is to help them recover, not to report a fault. A helpful message says plainly what went wrong, why if it matters, and what to do next, in the user’s language rather than the system’s. It avoids blame, avoids jargon and codes as the main content, and preserves the user’s work so recovery is possible.
An error message is a recovery tool
When an error message appears, the user has already hit a wall. The message arrives at a moment of frustration, and its purpose is to get the person moving again. This reframes it from a technical report of what the system detected into a recovery tool aimed at the person who is stuck. The measure of a good error message is whether the user knows what to do after reading it.
Messages that fail this test are common: a code with no explanation, a description of an internal state the user cannot act on, or a vague statement that something went wrong. Each leaves the person exactly where they were, stuck, now with the added feeling that the system is unhelpful.
Say what happened and what to do
A helpful message has a clear structure: what went wrong, in plain terms; why, if knowing helps the person act; and what they can do next. The next step is the most important part, because it is what turns a dead end into a path forward. Where the user can fix the problem themselves, the message should say how. Where they cannot, it should say what will happen or whom to contact.
- State the problem in the user’s language, not the system’s.
- Give a concrete next step the person can actually take.
- Reserve error codes for support diagnosis, not as the main message.
Do not blame, do not lose work
Tone matters at a moment of frustration. A message that implies the user did something wrong, even subtly, adds friction when the person is already annoyed. Neutral, plain language that takes responsibility for being clear works better than phrasing that assigns fault. Just as important, an error must not cost the user their work; preserving what they entered so they can correct and retry is part of what makes the message helpful rather than punishing.
Key takeaways
- An error message reaches the user at a moment of failure; its job is recovery.
- Measure a message by whether the user knows what to do after reading it.
- Say what went wrong in plain terms and give a concrete next step.
- Keep error codes for support diagnosis, not as the main content.
- Avoid blame and preserve the user’s work so they can correct and retry.
Frequently asked questions
- What is the purpose of an error message?
- To help the user recover from a failure, not to report what the system detected. The measure is whether the person knows what to do after reading it.
- Should error messages show error codes?
- Codes are useful for support diagnosis but should not be the main message; the user needs plain language about what happened and what to do next.
- Why does tone matter in error messages?
- They appear at a moment of frustration, so blaming or jargon-filled phrasing adds friction, while neutral plain language that gives a next step helps the person move on.
References
About the author
Maksym Bardakh
Co-founder & President
Maksym is a software engineer and product strategist focused on executive-function and behavioral system design. At BBMM he leads product direction across Flowo, TextPack, and Pillow, working at the intersection of human cognition and durable interface design.