← Back to Docs
Recipe

Writing helpful error messages

Users don't read errors — they scan them. Make every word earn its place.

The three-part formula

Every error message needs three things: what happened, why it matters, and what to do next. Skip any one and you've lost the user.

Bad

"Error 0x8004DE40: Authentication failed."

Good

"We couldn't verify your license. Your key may have expired. Renew at getnimbus.net/account or contact support."

Rules of thumb

  • 1.Never blame the user — "you did X wrong" becomes "X didn't work as expected."
  • 2.Put the fix first, the cause second. Users scan for action.
  • 3.Drop error codes unless they're actionable. Nobody Googles hex.
  • 4.Match tone to severity. A typo in a form field isn't a system crash.

Pro tip: Write the error message before you write the code that throws it. If you can't explain the fix clearly, the UX is broken — not the error string.