A good error message tells someone exactly what went wrong and what to do about it; a bad one just says “Something went wrong” and leaves them stuck. Writing clear error messages and log lines for every failure path in an application is tedious, repetitive work — which is exactly why AI prompts are useful here, as long as you anchor them to real engineering principles instead of just asking for “better error messages.”
What Does Google’s Own Technical Writing Course Say Makes a Good Error Message?
Google’s technical writing guidance is blunt about the stakes: “failure is inevitable; failing to report failures is inexcusable.” That’s the first principle — never fail silently. The second is specificity: instead of a generic message like “Server error,” identify the actual root cause, whether that’s a network issue, a permission problem, or a status mismatch, so the person reading it understands what actually happened.
The guidance also emphasizes that error messages should move past just naming the problem into explaining how to fix it, ideally with a concrete example. And it treats error messages as a design component to plan alongside a feature, not something to bolt on afterward.
The Core Prompt: Rewriting a Generic Error Message
Feed the model the failure context, not just the current message text, so it has enough to make the message genuinely specific:
“Here is an error message and the situation that triggers it: Message: ‘[current message]’. Trigger: [describe what actually causes this, e.g. ‘API request times out after 30s when the upstream service is down’]. Audience: [developers / end users]. Rewrite this error message so it: (1) states specifically what failed, not a generic category, (2) explains what the user or developer should do next, (3) avoids blaming the user unless the input was genuinely invalid, and (4) stays concise. Provide two versions: one for a UI-facing message, one for a log line with more technical detail.”
A Prompt for Writing Log Lines That Are Actually Useful During an Incident
Log output has a different audience than a user-facing error — usually a tired engineer debugging at 2am. This prompt targets that:
“Write a structured log line (as a JSON object) for this failure: [describe the failure]. Include fields for: severity level, a short machine-searchable error code, a human-readable message describing what happened, the relevant identifiers (request ID, user ID, or resource ID as applicable), and a ‘likely_cause’ field with the most probable root cause. Do not include any sensitive data like passwords, tokens, or full request bodies.”
A Prompt for Auditing a File Full of Existing Error Messages
Most codebases already have dozens of inconsistent error strings scattered around. Batch review finds the worst offenders fast:
“Here is a list of error message strings from our codebase: [paste list]. Flag any message that: is too generic to act on (like ‘Error occurred’ or ‘Something went wrong’), uses inconsistent terminology for the same concept, blames the user for a system failure, or is missing any next-step guidance. For each flagged message, suggest a specific replacement.”
Don’t Let AI Invent Error Codes or Causes It Doesn’t Actually Know
This is the one place to be careful: an AI model doesn’t know your actual system architecture, so it can confidently invent a plausible-sounding “likely cause” that’s wrong. Always constrain the prompt to the causes you’ve actually described, and have an engineer verify any suggested root cause before it ships in a user-facing message or gets relied on during an incident.
Consistent error handling pairs naturally with clear API documentation and with unit tests that actually cover your failure paths, not just the happy path.
Frequently Asked Questions
Should a user-facing error message and a log line ever be identical?
Generally no. A user-facing message should be short, non-technical, and actionable for someone who isn’t a developer. A log line can and should carry far more technical detail — stack traces, request IDs, internal service names — that would just confuse or overwhelm an end user if shown directly to them.
Is it ever okay to show a generic error message?
Sometimes, for security reasons — you don’t want to reveal internal system details to a potential attacker through an error message. But Google’s guidance still applies here: the message shown to the user can be generic for security, as long as the full, specific detail is still captured in a log line the engineering team can access.
How much detail should go into a log line versus a monitoring alert?
A log line should capture everything needed to reconstruct what happened after the fact: identifiers, timestamps, and a specific description of the failure. A monitoring alert built from that log should generally be shorter and focused on what needs immediate human attention, with a link back to the full log entry for deeper investigation.
Source: Google for Developers – Technical Writing: General error handling rules.
