Web HIG tip #7: Errors should say what failed and how to fix it

[frozonfreak]

"Something went wrong" tells people that something broke. It doesn't tell them what broke or what to do next.

Web HIG tip #7 (Quick #34 / HIG-ERR-001, and Quick #57): Error states must say what failed, why (when known), and how to recover. Error messages must be specific and actionable, not "Invalid input."

Why it matters

Vague errors push the work back onto the user:

• "Invalid input" on a long form makes people re-check every field to find the one that's wrong
• "Something went wrong" doesn't say whether to retry, wait, or contact support, so people guess or give up
• Without a way to recover, people abandon the task, open support tickets, or try the same thing again and fail again
• A specific message is also easier to search for, report, and debug

The rule of thumb

Ask: after reading this error, does the user know what to do next?

If not, rewrite it.

<!-- Don't: no field, no reason, no fix -->
<p class="error">Invalid input.</p>

<!-- Do: tie the error to the field and say how to fix it -->
<label for="start-date">Start date</label>
<input id="start-date" type="date" aria-invalid="true"
       aria-describedby="start-date-error">
<p id="start-date-error">Enter a date after today.</p>

Linking the message with aria-describedby is the same pattern from tip #4 (Quick #80). The new part here is the wording. On long forms, also list the errors in a summary at the top (Quick #51).

For an email field, "Enter an email address like name@example.com" beats "Invalid email." For a failed save, "We couldn't save your changes because the connection dropped. Your edits are still here. Try again." beats "Error 500."

Do this instead

• Say what failed, in plain words, next to the thing that failed
• Say why when you know it, without blaming the user or exposing internal details
• Give a clear way to recover: what to change, a retry button, or who to contact
• Keep what people already entered so fixing one field doesn't mean starting over. The Web HIG's error taxonomy (HIG.md §2.5) requires preserving input on validation errors and form state on network errors
• On a form, move focus to the first invalid field so people land where the fix is

Quick check for your app

Trigger three errors on purpose: one invalid field, one failed save, and one expired session. For each, read only the message. Can you tell what failed and what to do next without guessing? If any message just says "Invalid," "Error," or "Something went wrong," rewrite it.

---

The Web HIG is a behavioral contract for how the web should behave, not a component library. Design systems define how it looks. The Web HIG defines how it behaves.

• GitHub: Web HIG tip #7: Errors should say what failed and how to fix it #16
• Hashnode: https://thewebhig.hashnode.dev/errors-should-say-what-failed-and-how-to-fix-it-web-hig-tip-7
• Dev.to: https://dev.to/frozonfreak/errors-should-say-what-failed-and-how-to-fix-it-web-hig-tip-7-fo4
• Bluesky: https://bsky.app/profile/sastha.bsky.social/post/3mxdw2pmbhc2l