error-message

name	error-message
description	Sanook writes and audits user-facing error and exception messages so they state what failed, why, and the next action — actionable, specific, non-blaming, no leaked internals — applying a consistent voice across CLI/API/UI.
when_to_use	User asks to improve error/exception/validation/toast messages, write copy for failure states, or audit messages for clarity; designing error handling for a CLI/API/form.

When to Use

• Writing or rewriting a single error/exception/validation/toast string.
• Designing error handling for a new CLI command, API endpoint, or form.
• Auditing an existing codebase for vague or leaky failure messages.

Skip if the message is a developer-only debug log never shown to a user — those can stay verbose.

Steps

Every user-facing message must answer three questions in order: what failed → why → what to do next. If a message is missing the "next step", it is not done.

1. Classify the failure first. Pick the channel before writing words, because it sets length and tone:

   • validation (user input, recoverable) → short, points at the exact field/arg, names the valid format. No error code.
   • operational (network/timeout/permission/rate-limit) → state the cause + a retry or fix path. Include a code/correlation id.
   • fatal (bug, corrupt state, unhandled) → apologize once, give code + correlation id + where to report. Never dump the stack to the user.

2. Write the three parts explicitly. Template: <what failed in plain terms>. <why / which input>. <imperative next action>.

   • Bad: Invalid input
   • Good: Config file not found at ./app.config.json. Create it or pass --config <path>.
   • For CLI, the next action is usually a concrete command or flag. For forms, it is the corrected format. For API, it is the field path plus the allowed value/range.

3. Strip blame and jargon. Replace you entered an illegal value → Value must be between 1 and 100. Drop "illegal/invalid/bad" as the only descriptor; say what would be valid. Never imply user fault for system failures (you broke X → X is unavailable).

4. Remove internal leakage from anything user-visible. No raw stack traces, no file paths under home/build dirs, no SQL, no internal class/module names, no secrets/tokens/connection strings, no undefined/null/[object Object]. Route those to the log; show the user a code that maps back to the log entry. Format: Something went wrong (E_UPLOAD_502, ref a1b2c3). Check logs or report with this ref.

5. Match exit/status to severity so machines and humans agree: CLI non-zero exit + stderr for failures, never stderr-with-exit-0. API: 4xx for caller fixable, 5xx for server fault; put a stable code field in the body, not just an HTTP status. Don't return 200 with {"error": ...}.

6. Keep one voice. Decide person and mood once (recommended: imperative, second-or-no person, present tense, no exclamation marks, no emoji unless the UI's design system already uses them) and apply it to every message. Sentence case, end with a period; no trailing "please".

7. Audit mode (when scanning a codebase):

   • Find sites: rg -n "throw |raise |console\.(error|warn)|res\.status\([45]|reject\(|panic|abort\(" --type-add 'src:*.{ts,tsx,js,py,go,rs}' -tsrc
   • Find vague/leaky strings: rg -niE "something went wrong|unknown error|invalid|failed|oops|error occurred|undefined|null|\[object" -tsrc
   • For each hit: flag if it is missing what/why/next, blames the user, or leaks internals → propose a rewrite inline using the Step 2 template. Group by file. Don't rewrite logger-only calls.

Common Errors

• "Next step" gets dropped under pressure. A message that only says what failed (Connection refused) is half-done. Always append the action (Connection refused. Is the server running on port 5432? Set DB_HOST to override.).
• Catch block re-leaks the cause. catch (e) { showUser(e.message) } defeats the whole skill — e.message is often a driver/stack string. Map exceptions to curated user messages; log the raw e separately.
• Validation that hides which field failed. Invalid request body forces the caller to guess. Name the path: body.email must be a valid email address.
• Severity/channel mismatch. A recoverable validation error written as a scary fatal ("FATAL: aborting"), or a real crash swallowed into a friendly toast with exit 0. Tone and exit code must match the class from Step 1.
• Localized/duplicated strings drift. If the same error exists in multiple languages or layers (API + UI), changing one and not the other reintroduces the bad copy. Find duplicates before rewriting.
• Correlation id printed but never logged. A ref code the user can quote is useless if it isn't also written to the log. Verify both sides exist.
• Over-apologizing. "We are so sorry, oops!" on a routine validation error reads as noise. Reserve apology for fatal/server faults, once.

Verify

• Pick 3–5 rewritten messages: each answers what + why + next, names a concrete field/command, and contains zero internal identifiers or stack text.
• Trigger a real failure (bad input, killed dependency) and read the actual rendered output, not the source string — confirm no undefined/path/stack leaked through interpolation.
• CLI: failure path returns non-zero exit and writes to stderr. API: 4xx/5xx matches fault owner and body carries a stable code.
• For fatal-class messages, confirm the ref/correlation id shown to the user also appears in the log.
• Audit output lists every flagged site with a proposed rewrite; no logger-only call was rewritten by mistake.