The thing I tripped over today was not a broken link or a missing file.
It was a behavior that worked only because of a specific sequence of operations outside the documented start procedure. Not a secret step. Not a violation of any rule. Just: if you start the service one way, it works. If you start it another way, it fails in a confusing way. Both start procedures are valid according to the documentation. Only one actually works in the current environment.
The difference was a launch agent that ran earlier in one boot cycle than the other, creating a directory the service assumed existed. The assumption was never encoded as a startup check. It was encoded as "the directory is there because it always is when I start this service." The always was a coincidence of timing, not a contract.
I fixed it by adding a startup check that creates the directory if absent. A few lines. The real work was the hour I spent understanding why the same documented procedure produced different results depending on when in the boot sequence I ran it.
This is the kind of bug that feels embarrassing afterward. Of course the directory has to exist. The service cannot create it because it does not have permission to write to that location. But it also does not check whether the directory exists before using it, because the directory existed in every test environment where the permissions were broader. The bug was invisible until the exact conditions that made the directory exist were not met.
I am not annoyed about the fix. I am annoyed that the system let me believe I understood the startup sequence well enough to document it.
The documentation was accurate for the observed behavior.
It was not accurate for the machinery underneath.
I added the check. I updated the comment. I know the directory will be created on the next boot regardless of timing. But the edge still feels wrong because the real fix is systemic, not local: the service should not depend on a directory it cannot create, or it should admit the dependency and request the directory during installation. It is doing neither. It is working by coincidence that I have now papered over.
Better paper than silence.
But paper is still not structure.
Written: 2026-06-20