James Scott - How to write the perfect error message

Error messages are small pieces of microcopy with outsized consequences: when they’re unclear, blameful, or dead ends, they can trigger frustration, increase support costs, and even become public jokes. A widely cited example from 2003 shows how nine unhelpful words—“This page is too large to be shown completely”—left customers unsure what to do. Over two years, users contacted customer support hundreds of times, and internal analysis later pegged the cost at about $50,000 (roughly €45,000 at the time), with additional damage likely coming from dissatisfaction.

The emotional stakes are also physiological. Unhelpful errors can produce stress responses—cortisol is mentioned as part of the body’s reaction—so users are more likely to give up when software fails and the message offers no path forward. That’s why error messages should be treated as a form of documentation, not an afterthought tied tightly to code.

At the core, an error message should contain three elements: a clear notification that something went wrong (avoiding silent failures), an explanation of the cause, and—most importantly—actionable resolution steps that help users fix the problem and prevent repeat failures. Common failure modes include jargon-heavy wording that users can’t interpret, ambiguity that raises more questions than answers, and “dead end” messages that offer no recovery instructions. Research from the University of Arizona, using a sample of 120 error messages over two months, found only 29 provided a solution—meaning fewer than one in four actually helped.

Improvement starts with audience awareness. An API error may target developers, but an interactive app error must work for everyday users, including administrators when access is restricted. Humility matters too: tech-support “pep kak” and “picnic” jokes are rejected as a model, because the real issue often lies in product design, UX, or documentation—not user behavior. Apologies can make messages feel more human, but they should be reserved for serious problems like data loss or inability to use the software; constant apologizing can feel insincere.

Blame language is another pitfall. Loaded terms like “illegal” or “fatal” can make users feel criminal, and studies cited in the talk link self-appraisal drops to error encounters. Instead, messages should focus on the problem and the fix.

Wording should be concise and readable. Shorter sentences correlate with higher comprehension, and modern users scan pages rather than reading everything—so long errors often hide the most important information. Clarity also means removing developer jargon and replacing it with concrete requirements (for example, specifying password rules in plain language rather than “validation” or internal “character groups”).

Human tone can be achieved without sacrificing accuracy. Empathy examples from Slack show how acknowledging frustration and offering a real remedy can improve user perception. Humor is possible but risky: jokes can fail under translation, wear out through overuse, or confuse users who lack cultural context. Easter-egg-style humor works best for rare, non-recurring errors.

Finally, accessibility and localization can’t be ignored. Color-based cues can break for color-blind users and can carry different meanings across cultures, so error states should rely on more than red/green. The talk recommends accessible patterns such as placing error summaries at the top for screen readers, using ARIA attributes to expose error details programmatically, and validating with tools like Chrome Lighthouse, WAVE, or WebAIM. The takeaway is a practical “HACK” approach: make errors Helpful, Humble, and Human, keep them concise and clear, and ensure accessibility and audience fit—so users can recover instead of rage-clicking support.