Most error messages are written for the wrong reader.
They're written for the person who's watching when the thing breaks. You're at the terminal, the run fails, the message says connection refused or validation failed at step 3, and that's enough, because you have all the context in your head right now. You know what you were doing, what you changed, what the system was supposed to do. The message just has to jog a memory you already have.
The reader who actually needs the error state is someone else entirely, and they show up months later. I got talked into this view in a long comment thread on an earlier post, and it changed how I think about failure handling, especially for the async, agent-driven work I do a lot of now.
The reader you're not designing for
Here's the gap. When an interactive tool fails, there's a human in the loop who reacts immediately. The error can be terse because the context is live. You scroll up, you see the conversation, you fix it.
Async work has none of that. An agent runs a pipeline at 2am, something fails partway, and nobody sees it land. There's no conversation to scroll back through, no replay button, no warm context in anyone's head. Whoever investigates shows up cold, hours or weeks later, and the only thing they have is whatever the process wrote down before it stopped.
Which means, for that reader, the error state isn't a report about the failure. It is the failure, as far as they can ever see. If the record doesn't contain what they need to reconstruct what happened, the information is gone. Not hard to find. Gone.
That reframes the whole design question. It stops being "how do we format this error" and becomes "what does an investigator need to rebuild this run from nothing." Those are different specs, and almost every error message I've ever written was quietly answering the first one.
A message versus a record
The cleanest way I can put the distinction: most errors are a message, and what async work needs is a record.
A message is written for someone who shares your context. It can be short because it's pointing at things you both already know. "Validation failed" is a fine message when you're standing right there.
A record is written for someone who has nothing. It has to carry the context with it, because there's no shared memory to lean on. What was the input. What stage was this. What did the system believe was true when it decided to proceed. What got retried, how many times, with what result. A record is heavier on purpose, because its whole job is to survive the gap between the failure and the person who reads about it.
The test I use now: if I deleted the rest of the system and handed someone only this error state, could they tell me what went wrong? If the answer depends on context that lives anywhere other than the record itself, I'm writing a message and calling it a record.
The gap is also where organizations forget
There's a second reason the later reader has nothing, and it's not just time. It's people.
The person who built the system often isn't the person debugging it three months on. They've moved teams, moved companies, or just moved on to other work and dumped the context. So the investigator isn't even future-you, who at least shared your assumptions once. It's a stranger who was never in the room when the decisions got made.
That's the strongest version of the spec, and the most honest one. You're not writing for yourself later. You're writing for someone who has none of your context and never did, and who is meeting your system for the first time through its failure. If the error state only makes sense to someone who already understands the system, it's useless to exactly the person most likely to be reading it.
What this changes in practice
I haven't rebuilt everything. But a few habits shifted, and they're cheap.
I write error states as if the reader has no access to the rest of the run. Not "step 3 failed" but what step 3 was trying to do, what it received, and what it expected. The extra sentence costs nothing now and saves an hour later.
I treat the clean error state as the audit trail I'm choosing to have, rather than a thing I bolt on if there's time. In async work there's no other trail. Either the failure left evidence or it didn't, and that's decided when I write the handler, not when the incident happens.
And I stopped optimizing failure output for the demo. The version that looks good when you're watching it succeed is not the version that helps when it fails unattended. Those are different audiences, and the unattended one is the one that actually needs help.
The smallest version of the idea
If I compress all of it into one line, it's this: useful right now and useful in three months are different specs, and you usually only get to satisfy one of them, so pick the harder reader.
Pick the stranger. Write the record they'd need, not the message you'd understand. You won't be in the room when it's read, and the whole point of an error state is to work when you're not there.
I build WordPress plugins and write about AI tooling and security at https://raplsworks.com/.
