How to Write Error Messages That Help

Error are inevitable. It is part of your app. We can reduce the number of errors by making it more difficult to make mistakes, but the error will never go away. However, what you do to handle the errors makes all the difference. You can let your users scream in frustration, or you can guide them and make them like your app more. What’s it gonna be?

When we design the solution, we rarely think about the error messages. After all, how much is there to design anyway? We display the error message and hope users will do the right thing. As it turns out, an error message can make or break the user experience. These vague, unhelpful messages leave you frustrated and stuck. They don’t explain what happened or how to fix it. Instead of guiding you forward, they slow you down. This is more true, especially in enterprise software.

Enterprise software is complex. The technical source and the reasoning behind it can be difficult to explain. It can be related to permission, bad data, business processes, and so on, or it could be a combination of multiple things. The stakes are high as well because it can bring a stop to the whole company operation as well; a simple bug can stop all users from processing sales orders.

Error messages don’t have to be this way. A good error message can turn a bad moment into a helpful one. It can explain the issue clearly and show users how to move forward.

Why Bad Error Messages Are a Problem

A poorly written error message does more than confuse—it damages trust. When users encounter unclear or overly technical messages, they might feel like they’ve done something wrong or that the system is broken. This is a bad experience, and it can also increase support requests.

Here are some common problems with bad error messages:

• Too vague: “Something went wrong. Invalid value.” doesn’t tell users what happened or why.
• Too technical: Most users don’t understand error codes or jargon.
• No guidance: If there’s no clear solution, users are left guessing what to do next.

The goal of an error message should always be to solve a problem; not create more frustration.

Tips for Writing Better Error Messages

Want to improve your error messages? Here’s some tips:

1. Be clear about what went wrong

To begin with, make sure that you fully understand what happened before crafting the error message. Once you understand, tell users exactly what happened in simple, direct language. Avoid technical terms or generic phrases.

2. Tell the users what they need to know

Give the user the information on why the error occurs and what the impact is. Keep it short, but informative. Don’t go overboard, but don’t underplay it either. Provide enough context to be helpful. Users need the key details to solve the issue. Be specific.

3. Offer a solution

Whenever possible, tell users how to fix the problem themselves. This reduces frustration and avoids unnecessary support calls. A little guidance goes a long way.

4. Avoid blame or frustrating language

Error messages should feel neutral and helpful. Use a friendly, professional Tone. It should sound human, not robotic, or overly formal.
Avoid ALL CAPS, and be polite and reassuring.

5. Consider the best way to communicate the issue

Is it an information, warning, a hard error, a notification? Think about how you want to communicate and how you want the user to react accordingly.

6. Avoid using TestField when context is not clear

TestField offers a simple way to validate fields, but its usage should be reserved for situations where the context is clear to the user. Before using TestField, always consider if the user will understand the error message. If there’s any doubt, creating your own message is always better.

7. Use Actionable Errors when possible

Whenever possible, use Actionable Errors to help users fix the problem easily.

8. Standardise Your Messages

Error messages are located in all places. Agree on a tone, structure, and level of detail for your team so users get a consistent experience and patterns.

Example of the Error Messages:

❌ Missing Required Field.

✅ The External Document No. field is required. Please enter a value to proceed.

❌ File type not allowed.

✅ Only CSV files are supported for this import process. Please convert your file to CSV format and try again.

❌ Record already exists.

✅ A customer with email robert.townes@contoso.com already exists. Try using a different email or update the existing customer (10000 – Adatum Corporation).

❌ Stock unavailable.

✅ Only 5 ATHENS Desk are in stock. Adjust the quantity or place a backorder.

❌ Invalid date format.

✅ Enter the Posting Date in DD//MM/YYYY format.

❌ You entered the wrong Payment Method.

✅ Please specify the correct payment method before releasing the order.

❌ Failed to release the sales order.

✅ Sales Order 103021 cannot be released because the customer’s credit limit has been exceeded.

❌ Customer Price Group must be equal to RETAIL.

✅ Customer Price Group WHOLESALE on Document 101001 does not match with Customer Price Group on Customer Master 10000 (RETAIL). Please verify and update the Customer Posting Group.

❌ Wrong input. Please try again.

✅ The Posting Date cannot be before the Document Date. Please update the Posting Date.

❌ Import validation error.

✅ Item 1001 cannot be added to the sales order because it’s blocked. Please review the item and unblock if appropriate.

Final Thought

Users don’t read error messages for fun. They read them to fix something. If the message doesn’t help them do that, it’s failed its only job. Take the time to write messages that are clear, actionable, and tailored to the context. Your users and your support desk will thank you.