Error Writer#

Bad error messages are the #1 cause of unnecessary support tickets and debugging dead ends. Good error messages tell you what broke, why, and exactly what to do next.

Paste your existing error strings and get a complete rewrite — one version for users, one for logs, one for your API response body.

Works on any language. No config. No API keys.

---

Trigger Phrases#

• "rewrite error messages", "fix error messages", "improve error messages"
• "bad error message", "this error is confusing", "make errors clearer"
• "error message audit", "audit my errors", "review error strings"
• "write better errors", "improve UX of errors"
• "/error-writer"

---

How to Provide Input#

text

# Option 1: Paste error strings directly
/error-writer
"Something went wrong"
"Invalid input"
"Error: 500"
"Cannot read property 'id' of undefined"

# Option 2: Paste a code file with error messages
/error-writer
[paste errors.ts / errors.py / constants.js etc.]

# Option 3: Provide file path
/error-writer src/errors.ts

# Option 4: Specify audience
/error-writer --audience end-user
"User not found in database at line 42 of UserService.java"

# Option 5: Full audit mode
/error-writer --audit src/
(scans all source files for error message patterns)

---

Step 1: Classify Each Error Message#

Before rewriting, classify every error by two dimensions:

Dimension 1: Audience#

AudienceWho Reads ItChannelEnd userNon-technical: customer, student, patientUI toast, modal, page textDeveloperIntegrating your APIAPI response body, SDK exceptionOps/SRERunning your serviceServer logs, monitoring alertsInternal devDebugging locallyConsole, test output

Dimension 2: Error Category#

CategoryExamplesWhat the message needsValidationBad input format, missing required fieldWhat field, what's wrong, what format is expectedAuth/PermissionUnauthorized, forbiddenWhat was attempted, what permission is neededNot FoundMissing resourceWhat resource, what ID, what to checkRate LimitToo many requestsLimit, window, when to retryUpstream/DependencyThird-party service downWhich service, whether it's transient, what to doInternal/BugUnexpected server errorUser: reassurance + reference ID. Dev: full contextConflictDuplicate resource, state mismatchWhat already exists, how to resolveTimeoutRequest too slowWhat timed out, suggested next action

---

Step 2: Audit for Anti-Patterns#

Flag every error message that matches these patterns:

🔴 Critical Anti-Patterns#

1. Vague Generics — Tells the reader nothing actionable

text

❌ "Something went wrong"
❌ "An error occurred"
❌ "Operation failed"
❌ "Invalid request"
❌ "Error 500"
❌ "Unexpected error"

2. Leaked Internals — Internal details visible to end users

text

❌ "NullPointerException at UserService.java:42"
❌ "Error: Cannot read property 'id' of undefined"
❌ "SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry"
❌ "Connection refused: 127.0.0.1:5432"
❌ Stack traces in API responses

3. Wrong Audience — Developer speak in end-user messages

text

❌ "JWT token expired" (end-user message)
❌ "Invalid UUID format" (end-user message)
❌ "HTTP 422 Unprocessable Entity" (end-user message)
❌ "Database constraint violation" (end-user message)

4. Missing Context — No information about what went wrong or what to do

text

❌ "Email invalid" — which email? what format is valid?
❌ "Not found" — what wasn't found?
❌ "Access denied" — what requires access? how to get it?
❌ "Please try again" — when? how many times? is it transient?

🟠 High Anti-Patterns#

5. Fear-inducing language — Overstates severity for end users

text

❌ "FATAL ERROR: system failure"
❌ "CRITICAL: data corruption detected"
❌ "WARNING: your account may be compromised"
   (when it's just a session timeout)

6. Blame language — Implicit or explicit blame

text

❌ "You provided an invalid email address" → "The email address doesn't match the expected format"
❌ "You must be logged in" → "Sign in to continue"
❌ "User error: ..." → just describe what happened

7. No recovery path — Error with no next step

text

❌ "Payment declined." (end)
   Better: "Payment declined. Check that your card number and expiry date are correct, then try again."

🟡 Medium Anti-Patterns#

8. Inconsistent capitalization/punctuation

text

❌ Mix of: "Email is required." / "password required" / "Phone Required!"

9. All-caps for non-critical errors

text

❌ "ERROR: EMAIL NOT FOUND"

10. Numeric codes without explanation

text

❌ "Error code: 10042" with no description

---

Step 3: Rewrite Each Message#

Apply the 3-part formula to every error:

text

[What happened] + [Why it happened] + [What to do next]

Rules by Output Channel#

UI / End-User Facing

• Plain language, no technical terms
• Short: 1-2 sentences max
• Reassuring tone — not scary
• Clear next action in the same sentence or as a button label
• Never expose: exception names, file paths, line numbers, SQL, IDs

API Response Body (for developer integrating your API)

• Include: error (machine-readable code), message (human-readable), details (optional array)
• Machine-readable codes should be SCREAMING_SNAKE_CASE
• Include: request ID for tracing, documentation link if complex
• Can include: field names, constraint names, allowed values

json

{
  "error": "VALIDATION_ERROR",
  "message": "The request body contains invalid fields.",
  "details": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Must be a valid email address (e.g., user@example.com)"
    },
    {
      "field": "age",
      "code": "OUT_OF_RANGE",
      "message": "Must be between 13 and 120"
    }
  ],
  "request_id": "req_7f3a9b"
}

Server Logs / Ops

• Include ALL context: user ID, request ID, timestamp, trace ID
• Include exception type and stack trace
• Structured (JSON) preferred
• No sanitization — ops team needs raw details

json

{
  "level": "error",
  "timestamp": "2026-03-18T10:42:00Z",
  "message": "Payment processing failed",
  "error_type": "StripeConnectionError",
  "user_id": "usr_abc123",
  "request_id": "req_7f3a9b",
  "stripe_error_code": "connection_error",
  "retry_count": 3,
  "stack": "..."
}

---

Step 4: Output Report#

markdown

## Error Writer Report
Input: [N] error messages analyzed | [M] anti-patterns found

### Audit Summary

| Severity | Count | Category |
|----------|-------|---------|
| 🔴 Critical | 4 | Vague generics (3), Leaked internals (1) |
| 🟠 High | 2 | Missing recovery path (2) |
| 🟡 Medium | 1 | Inconsistent formatting (1) |

---

### Rewrites

---

**❌ BEFORE:** `"Something went wrong"`
**Category:** Validation | **Audience:** End user | **Anti-pattern:** Vague generic

**✅ AFTER:**

*UI message:*
> "We couldn't save your changes. Check that all required fields are filled in and try again."

*API response:*
```json
{
  "error": "SAVE_FAILED",
  "message": "Unable to save changes. Ensure all required fields are populated.",
  "request_id": "req_{{id}}"
}

Log entry:

text

ERROR [UserService.save] Failed to persist user update | user_id={{id}} | validation_errors={{errors}} | request_id={{id}}

---

❌ BEFORE: "Cannot read property 'id' of undefined" Category: Internal bug | Audience: Leaked to end user | Anti-pattern: Leaked internals

✅ AFTER:

UI message (what the user sees):

"Something unexpected happened on our end. Your data is safe. Please try again or contact support if this persists. [Reference: {{request_id}}]"

Ops log (what engineers see):

text

ERROR [UserController.getUser] Null reference: user object was undefined when accessing .id
Expected: User object from DB lookup
Got: undefined (possible cache miss or deleted user)
user_id_param={{param}} | request_id={{id}} | stack={{trace}}

Action required: Add null check before accessing .id. Investigate why DB lookup returned undefined for valid-format ID.

---

❌ BEFORE: "Invalid input" Category: Validation | Anti-pattern: Missing context + Vague

✅ AFTER:

UI: "Please check the highlighted fields — some information is missing or in the wrong format."

API:

json

{
  "error": "VALIDATION_ERROR",
  "message": "One or more input fields are invalid.",
  "details": [
    {"field": "{{field_name}}", "message": "{{specific constraint}}"}
  ]
}

Log: WARN [Validator] Input validation failed | fields={{fields}} | rules_violated={{rules}} | request_id={{id}}

---

Copy-Paste Constants File#

typescript

// errors.ts — generated by phy-error-writer
export const Errors = {
  SAVE_FAILED: {
    code: "SAVE_FAILED",
    ui: "We couldn't save your changes. Check that all required fields are filled in and try again.",
    log: "Failed to persist entity update",
  },
  VALIDATION_ERROR: {
    code: "VALIDATION_ERROR",
    ui: "Please check the highlighted fields — some information is missing or in the wrong format.",
    log: "Input validation failed",
  },
  INTERNAL_ERROR: {
    code: "INTERNAL_ERROR",
    ui: "Something unexpected happened on our end. Your data is safe — please try again or contact support.",
    log: "Unhandled internal error",
  },
} as const;

---

Error Message Style Guide (project-specific, generated)#

Based on the messages analyzed, your project should follow these conventions:

• Sentence case, ending with a period
• End-user messages: present tense, active voice, no technical terms
• Include recovery action in every end-user message
• API error codes: SCREAMING_SNAKE_CASE
• Log entries: include request_id and user_id as structured fields on every error

text

---

## Quick Mode

For a single error message:

Input: "User not found in database at UserService.java:42"

Quick Rewrite: UI: "We couldn't find your account. Double-check your email address, or sign up if you're new." API: {"error": "USER_NOT_FOUND", "message": "No account found with that identifier."} Log: ERROR [UserService] User lookup returned null | query_param={{id}} | request_id={{id}}

Anti-patterns fixed: Leaked internals (Java file path), Wrong audience (database mention)

text

---

## Why This Matters

A study of developer productivity found that **unclear error messages are the #1 cause of unnecessary support tickets** and the **#2 cause of debugging time wasted** (after missing logs). For an API, bad error messages mean:

- Integrators file support tickets for things they could self-serve
- Developers spend hours on errors that a good message would resolve in minutes
- Security information leaks via stack traces in production responses
- End users abandon flows that could be recovered with a clear next step

This skill turns error message improvement from a "someday" task into a 5-minute audit.

---

## Author

**[Canlah AI](https://canlah.ai)** — Run performance marketing without breaking your brand.

- GitHub: [github.com/PHY041](https://github.com/PHY041)
- All Skills: [clawhub.ai/PHY041](https://clawhub.ai/PHY041)