The agent reported success. The job “completed.” Then the next step in your pipeline received nothing, and you spent an evening chasing the mystery.
Here’s the liberating truth most solo builders don’t reach until it costs them: your agent’s failures are almost never dramatic. They’re mechanical, and mechanical means diagnosable.
The bug was one missing closing bracket. The fix was reading one number in a log file. There is no genius in it — and that’s exactly the good news.
The myth of the “incomprehensible” failure
When an agent does something wrong, the instinct is to reach for the big explanations: the model is hallucinating, the prompt was too vague, the model “just isn’t good enough yet.” So you rewrite prompts, swap models, and buy a more expensive tier.
Meanwhile the actual failure sat in a single log line the whole time, untouched.
Agent failure modes are, overwhelmingly, the unglamorous kind:
- A JSON field that’s one closing bracket short of valid.
- A permission scoped one level too narrow.
- An environment variable that never made it into the shell.
- A file read from the wrong directory, so it silently gets an empty string.
- An “if” that never branches because the condition compares a string to a number.
None of these need a better model. All of them are visible to anyone willing to read the output instead of the summary.
Why people skip the diagnosis
The tragedy is that diagnosis looks like work but feels like nothing. Reading a log isn’t a satisfying story. “I swapped to a smarter model and it worked” is a story. “I found a missing bracket” is not — so nobody brags about it, and the cargo cult of model-swapping survives.
But the two-minute log read is the highest-return habit in a solo setup. It’s the same discipline as our post on the “done” verification ritual — that one catches a failure by forcing you to witness the output; this one finds the failure once it’s happened. And it’s the flip side of knowing your agent patterns: the pattern tells you where the failure mode lives; the log tells you what actually broke.
The diagnosis discipline
When an agent “fails mysteriously,” resist the urge to broaden the investigation. Narrow it instead.
Reproduce before you theorize. Re-run the exact same input. If it fails the same way every time, it’s deterministic — which means it’s a bug in the input, the config, or the wiring, not the model. Non-determinism (a different wrong answer each run) is the only case where the model itself, or its temperature, is the suspect.
Read the rawer output, not the diagnosis. The agent will happily give you a confident explanation of its own failure — and that explanation is often another hallucination wearing a lab coat. Skip it. Look at the input it received, the tool call it made, and the raw bytes that came back. The truth is in the payload, not the apology.
Find the single smallest number that’s wrong. A count, an exit code, a status, a timestamp. Locate the one place where reality diverges from what the agent assumed, and you’ve found your root cause. Agent bugs collapse to a single line with alarming regularity.
Fix the boundary, not the behavior. Once you see it, the fix is usually a rule or a check, not a longer prompt. “Always parse the JSON and fail loudly on malformed,” beats “try harder to output valid JSON.” You’re hardening the system, not pleading with it.
The calm that comes from boring failures
This mindset changes how a solo builder sleeps. A “mysterious” failure is anxiety — an unknown unknown that might be anywhere. A mechanical failure is a known unknown, and a known unknown is a ten-minute job.
The day you stop reaching for the model and start reaching for the log is the day your agents stop being mysterious and start being legible the way your own code is legible. Both break the same way: one line at a time, in the open, waiting for you to read it.
Your agent didn’t fail mysteriously. It failed boringly. Go read the line.
Sources
- Multiple agent post-mortems on Hacker News and Indie Hackers (2025–2026). Recurring signature: agents report success while the underlying action fails mechanically (missing bracket, mis-scoped permission, empty env var, wrong working directory); the failures are deterministic and visible in the raw tool output, not the summary.
- Agent reliability and error-taxonomy literature. Tool-use and reflection failure modes (Zheng et al., AgentErrorTaxonomy, arXiv:2509.25370) document how agents confabulate explanations when asked to self-report; the remedy is inspecting the executed action, not the agent’s hindsight account.
- Continuous-integration and observability practice. The discipline of locating a single divergent count, exit code, or status as the root-cause anchor is the same “find the one number that’s wrong” move that CI systems formalize — the log is the ground truth, the narrative is speculation.