DEV Community

Cover image for Your Error Messages Are Written for Developers, Not Users

Your Error Messages Are Written for Developers, Not Users

Open the network tab on almost any web app, trigger a failed request, and you'll usually find one of two things staring back at the user: a raw stack trace, or a message so generic it might as well say "something happened."

Neither one helps. Both exist for the same reason they were written by developers, for developers, and never translated for the person actually using the product.

The Error Message Nobody Designed

Most UI elements go through some level of design scrutiny. Buttons get spacing decisions. Forms get validation states. But error messages? They're usually whatever string got thrown at the moment something broke, copy-pasted straight from a try/catch block into a toast notification.

"Error 500: Internal Server Error." "Failed to fetch." "Unexpected token in JSON at position 4." These are diagnostic breadcrumbs for engineers debugging a system. To a user trying to submit a form or complete a purchase, they're just noise confirmation that something went wrong, with zero indication of what to do next.

This is where good web app design services earn their keep not in the buttons and layouts everyone notices, but in the failure states nobody plans for until users start complaining.

Why This Keeps Happening

It's not that teams don't care. It's that error handling sits at the intersection of two disciplines that rarely talk to each other at the moment. Backend logic throws whatever exception the code produces. The front end just needs something to display so the app doesn't silently freeze. Nobody's job, at that moment, is to ask: "what should the user actually understand right now?"

The result is a UI layer that's polished everywhere except the one place users encounter when things go wrong which, ironically, is exactly when clear communication matters most.

What a Good Error Message Actually Does

A well-designed error message does three things a raw exception never does. It tells the user what happened, in plain language not "Error: NetworkException," but "We couldn't save your changes." It tells them what to do next, retry, check their connection, contact support rather than leaving them staring at a dead end. And it preserves their work wherever possible, so a failed submission doesn't mean retyping an entire form from scratch.

None of this requires exposing internal system details. In fact, good error UX often means deliberately hiding them. A user doesn't need to know the request timed out at the load balancer level. They need to know their action didn't go through, and what their options are now.

The Optimistic Trap

There's a related failure mode worth flagging: apps that assume the happy path so thoroughly that error states were never designed at all, just inherited from whatever the framework threw by default. This is common in fast-moving products where shipping the feature took priority over shipping the failure. The result is an app that feels confident and modern until the exact moment it breaks, at which point it suddenly looks like nobody was in the room when it shipped.

A Simple Fix Most Teams Skip

You don't need a full design system overhaul to fix this. Start by auditing every place your app currently surfaces a raw error string to a user from submissions, API calls, payment flows and ask, for each one: does this tell the user what happened and what to do next? If the answer is no, it's a five-minute rewrite, not a redesign.

The technical work of catching an error is often already done. The design work translating that error into something a human can act on is usually the missing half.

Conclusion

Error messages are one of the few UI elements users only see when something's already gone wrong, which makes them one of the highest-stakes moments in the whole product. Treating them as an after thought, a leftover string from a try catch block quietly erodes trust every time it happens. Treating them as a real design surface, with the same care given to onboarding or checkout, turns a moment of friction into a moment of reassurance.

Top comments (0)