My parser reported a parse error on a file that was never malformed

A build step that reads requirement tables out of a document reported this, every run: FAIL_MAP reason=parse reason=parse has an obvious reading. Either the document is malformed or the parser is broken. A person following that reason code goes and looks at one of those two things. Both were fine. The fix changed neither, and it was one line. What was actually wrong The reader does not scan a document for anything that looks like a table. It reads a declaration that says which parts of which file carry structured rows, and treats everything else as prose. That is deliberate: a document is mostly sentences, and a reader that guesses which sentences are data will eventually guess wrong in a way nobody notices. The block for this document declared no structured forms at all. [[faces]] name = "requirements" file = "..." + dod_headers = ["Definition of Done"] With no declaration, the rule "anything not declared is prose" applied to the whole file. Two hundred and fifty-six perfectly well-formed rows were read as paragraphs, the reader found none of what it was required to find, and it reported that as a parse failure. before: FAIL_MAP reason=parse after: OK_MAP dod_rows=256 declared_faces=1 The document was not edited. The parser was not edited. Why the reason code sent me the wrong way reason=parse names the stage that failed , not the cause. Parsing is where the symptom appeared, because parsing is what produced nothing. what the code says where it points where the defect was reason=parse the parser, the document the declaration that connects them A failure at stage N is caused at stage N or earlier, and reason codes are almost always written at N. Mine named its own stage and was technically accurate and practically misleading, which is the worst combination because there is nothing to correct. The more useful reason code, had it existed, would have been the thing the reader could actually observe about its own inputs: this file is declared and declares zero structure