Writing Error Messages
Quick Start
Before writing, identify:
- Audience: end user, admin, developer, support agent, or operator.
- Failure: what action failed and what still happened successfully.
- Cause: known, unknown, user-correctable, service-side, third-party, or security-sensitive.
- Recovery: what the reader can do now, what the system will do next, and where they can get help.
Then write this shape:
[What happened]
[Reassurance if useful]. [Why it happened, if known and safe]. [Specific next action]. [Backup path if it keeps happening].
Example:
Unable to connect your account
Your changes were saved, but we couldn't connect the account because of an issue on our end. Try connecting again. If this keeps happening, contact support.
Core Rules
| Rule |
Do |
Avoid |
| Say what happened |
"We couldn't save your file." |
"Something went wrong." |
| Say what was not affected |
"Your draft was saved." |
Leaving the user to wonder if data was lost |
| Give the next action |
"Check the card number and try again." |
"OK" / "Close" as the only path |
| Use plain language |
"We couldn't connect to Dropbox." |
"Fetch failed" / "credentials denied" |
| Avoid blame |
"Store name is required." |
"You forgot to enter a store name." |
| Match the stakes |
Calm, direct, respectful |
"Oops!" / jokes / cutesy tone |
| Be specific when safe |
"Enter a date in the past." |
"Invalid input." |
| Be generic when security requires it |
"Invalid email or password." |
"That email exists, but the password is wrong." |
Message Anatomy
Use only the pieces the situation needs.
| Piece |
Purpose |
Pattern |
| Title |
Summarize the failed action |
"Couldn't save changes" |
| Body |
Explain consequence and cause |
"Your changes are still open, but we couldn't save them because the connection dropped." |
| Primary action |
Tell the reader what to do |
"Try again", "Update details", "Choose another file" |
| Backup path |
Provide a way out |
"If this keeps happening, contact support." |
| Diagnostic detail |
Help technical readers or support |
Error code, request ID, expected/received values, log location |
Keep UI body copy to 1-2 sentences when possible. Put longer diagnostic details in expandable text, logs, or support context.
References
- Open
references/source-backed-patterns.md when auditing many messages, resolving wording tradeoffs, or checking source-backed rationale.
- Open
references/rewrite-examples.md when rewriting multiple messages or testing whether the skill is producing the right shape.
Validation and Form Errors
For field-level errors:
- Put the message next to the field and summarize errors at the top for long forms.
- Match the field label or question so the reader can connect the message to the control.
- Say how to fix it, not only that it is wrong.
- Preserve the user's input so they can correct it.
- Do not validate before the user has had a fair chance to finish typing.
Good patterns:
Enter an email address
Enter a date in the past
Password must be at least 12 characters
Choose a file smaller than 10 MB
Avoid:
This field is required
Invalid input
You entered an illegal value
Validation failed
Placement, Accessibility, and Empty States
- Put the error where the reader is looking: near the field, control, toast source, or failed item.
- Do not rely on color alone. Include visible text, icons or labels, and machine-readable semantics when working in UI code.
- For form pages, move focus to the error summary or first error according to the product's accessibility pattern.
- Preserve the user's work whenever possible.
- Do not turn an empty result into an error. If nothing failed, write an empty state: "No invoices found" plus the next useful action.
Security and Privacy Gate
Specificity is not always better. Use a generic message when detail could reveal account existence, permissions, private data, system internals, fraud signals, or security policy.
Use generic copy for login and account recovery:
Invalid email or password
If an account exists for that email address, we'll send password reset instructions.
Do not reveal:
That email exists, but the password is wrong
This account is locked
No account found for this email
If the user needs help, give a safe path: support, recovery instructions, request ID, or an audit-safe explanation.
Developer-Facing and CLI Errors
When the reader can act on technical details, include them in a structured way:
Could not read config file
Expected TOML at ./app.config.toml, but found invalid syntax on line 12: missing closing quote.
Fix the syntax and run `app deploy` again.
Useful details:
- What command, file, field, or resource failed.
- What was expected and what was received.
- The smallest fix or next diagnostic command.
- A request ID, error code, or log path when support/debugging needs it.
Still avoid stack traces, raw exception names, and internal service names unless the audience can use them.
When Asked for a Generic Error
Do not accept "just write a generic error" without checking whether the product can do better. Ask:
- What action was the user trying to complete?
- What triggered this error in the code or service?
- Is the cause known, unknown, intermittent, or security-sensitive?
- Was anything saved, sent, charged, deleted, or left unchanged?
- Can the user fix it, retry, wait, use another path, or contact support?
- How often does it happen, and does it block the main flow?
If the cause is truly unknown, use a generic-but-actionable fallback:
Something went wrong
Refresh the page and try again. If this keeps happening, contact support with request ID {request_id}.
Final Check
Before shipping, verify the message answers the reader's questions:
- What happened?
- Did I lose anything or create a duplicate?
- Why did this happen, if it is safe to say?
- What can I do next?
- What happens if I do nothing?
- Where can I get help if the fix does not work?
1---2name: writing-error-messages3description: Use when writing, reviewing, or rewriting user-facing error messages, validation messages, form errors, empty/error states, auth errors, failure notifications, retry/support copy, CLI errors, or API errors humans will read. Helps make errors specific, actionable, non-blaming, accessible, and safe without leaking sensitive details.4---56# Writing Error Messages78## Quick Start910Before writing, identify:11121. **Audience:** end user, admin, developer, support agent, or operator.132. **Failure:** what action failed and what still happened successfully.143. **Cause:** known, unknown, user-correctable, service-side, third-party, or security-sensitive.154. **Recovery:** what the reader can do now, what the system will do next, and where they can get help.1617Then write this shape:1819```text20[What happened]21[Reassurance if useful]. [Why it happened, if known and safe]. [Specific next action]. [Backup path if it keeps happening].22```2324Example:2526```text27Unable to connect your account28Your changes were saved, but we couldn't connect the account because of an issue on our end. Try connecting again. If this keeps happening, contact support.29```3031## Core Rules3233| Rule | Do | Avoid |34|------|----|-------|35| Say what happened | "We couldn't save your file." | "Something went wrong." |36| Say what was not affected | "Your draft was saved." | Leaving the user to wonder if data was lost |37| Give the next action | "Check the card number and try again." | "OK" / "Close" as the only path |38| Use plain language | "We couldn't connect to Dropbox." | "Fetch failed" / "credentials denied" |39| Avoid blame | "Store name is required." | "You forgot to enter a store name." |40| Match the stakes | Calm, direct, respectful | "Oops!" / jokes / cutesy tone |41| Be specific when safe | "Enter a date in the past." | "Invalid input." |42| Be generic when security requires it | "Invalid email or password." | "That email exists, but the password is wrong." |4344## Message Anatomy4546Use only the pieces the situation needs.4748| Piece | Purpose | Pattern |49|-------|---------|---------|50| Title | Summarize the failed action | "Couldn't save changes" |51| Body | Explain consequence and cause | "Your changes are still open, but we couldn't save them because the connection dropped." |52| Primary action | Tell the reader what to do | "Try again", "Update details", "Choose another file" |53| Backup path | Provide a way out | "If this keeps happening, contact support." |54| Diagnostic detail | Help technical readers or support | Error code, request ID, expected/received values, log location |5556Keep UI body copy to 1-2 sentences when possible. Put longer diagnostic details in expandable text, logs, or support context.5758## References5960- Open `references/source-backed-patterns.md` when auditing many messages, resolving wording tradeoffs, or checking source-backed rationale.61- Open `references/rewrite-examples.md` when rewriting multiple messages or testing whether the skill is producing the right shape.6263## Validation and Form Errors6465For field-level errors:6667- Put the message next to the field and summarize errors at the top for long forms.68- Match the field label or question so the reader can connect the message to the control.69- Say how to fix it, not only that it is wrong.70- Preserve the user's input so they can correct it.71- Do not validate before the user has had a fair chance to finish typing.7273Good patterns:7475```text76Enter an email address77Enter a date in the past78Password must be at least 12 characters79Choose a file smaller than 10 MB80```8182Avoid:8384```text85This field is required86Invalid input87You entered an illegal value88Validation failed89```9091## Placement, Accessibility, and Empty States9293- Put the error where the reader is looking: near the field, control, toast source, or failed item.94- Do not rely on color alone. Include visible text, icons or labels, and machine-readable semantics when working in UI code.95- For form pages, move focus to the error summary or first error according to the product's accessibility pattern.96- Preserve the user's work whenever possible.97- Do not turn an empty result into an error. If nothing failed, write an empty state: "No invoices found" plus the next useful action.9899## Security and Privacy Gate100101Specificity is not always better. Use a generic message when detail could reveal account existence, permissions, private data, system internals, fraud signals, or security policy.102103Use generic copy for login and account recovery:104105```text106Invalid email or password107If an account exists for that email address, we'll send password reset instructions.108```109110Do not reveal:111112```text113That email exists, but the password is wrong114This account is locked115No account found for this email116```117118If the user needs help, give a safe path: support, recovery instructions, request ID, or an audit-safe explanation.119120## Developer-Facing and CLI Errors121122When the reader can act on technical details, include them in a structured way:123124```text125Could not read config file126Expected TOML at ./app.config.toml, but found invalid syntax on line 12: missing closing quote.127Fix the syntax and run `app deploy` again.128```129130Useful details:131132- What command, file, field, or resource failed.133- What was expected and what was received.134- The smallest fix or next diagnostic command.135- A request ID, error code, or log path when support/debugging needs it.136137Still avoid stack traces, raw exception names, and internal service names unless the audience can use them.138139## When Asked for a Generic Error140141Do not accept "just write a generic error" without checking whether the product can do better. Ask:142143- What action was the user trying to complete?144- What triggered this error in the code or service?145- Is the cause known, unknown, intermittent, or security-sensitive?146- Was anything saved, sent, charged, deleted, or left unchanged?147- Can the user fix it, retry, wait, use another path, or contact support?148- How often does it happen, and does it block the main flow?149150If the cause is truly unknown, use a generic-but-actionable fallback:151152```text153Something went wrong154Refresh the page and try again. If this keeps happening, contact support with request ID {request_id}.155```156157## Final Check158159Before shipping, verify the message answers the reader's questions:1601611. What happened?1622. Did I lose anything or create a duplicate?1633. Why did this happen, if it is safe to say?1644. What can I do next?1655. What happens if I do nothing?1666. Where can I get help if the fix does not work?
joshuadavidthomas