What Actually Breaks a PDF-to-Word Conversion: Lessons from Rebuilding Ours

Most explanations of "why PDF-to-Word conversion is hard" stay abstract. This one doesn't — it's a walk through specific, real bugs found and fixed while rebuilding this site's own PDF-to-Word converter against a genuinely difficult real-world test document (an audited financial statement, dozens of pages, tables, embedded signature images, and multi-column notes), because the abstract version undersells just how many small, precise decisions a correct conversion actually depends on.

Bug one: a sentence that lost its bullet point

A bulleted line in the source document read something like "...our opinion. The risk of not detecting a material misstatement resulting from fraud is higher..." — a single bullet point whose text wrapped onto a second line. The converter misread the gap right after "opinion." as a table-style column break instead of an ordinary line wrap, because justified text sometimes stretches the space after a period further than usual to fill the line width evenly — and a gap that wide had, up to that point, reliably meant "this is a new column," not "this sentence just ended." The practical effect: the rest of the sentence lost its bullet marker and indentation entirely, and the line got misclassified as a two-column table that didn't exist. The fix required teaching the converter a specific rule: a wide gap immediately after terminal punctuation (a period, question mark, exclamation point) followed by a capitalized word is a sentence boundary, not a column boundary — checked before the column-detection logic runs, not after.

Bug two: a page number that was actually hardcoded

An earlier version of the page-numbering feature technically produced numbers at the bottom of each page — but they were static values written into the document once, not real page-number fields. That's an invisible bug in a three-page test document (the numbers happen to be right) and a completely broken one the moment pages get added, removed, or reordered after conversion, since the numbers never update. The fix meant generating an actual computed field in the document's internal structure — the same mechanism Word itself uses for "insert page number" — which recalculates automatically no matter how the document changes afterward, rather than a fixed value that happened to be correct once.

Bug three: images that ignored their original spacing

A logo and a tagline sat together in a specific spot on the source PDF's cover page, with a large deliberate gap above them — real blank space the original document's designer put there on purpose. The first version of the converter placed both images immediately after whatever paragraph came before them, with no awareness that there was ever supposed to be a gap, because a basic inline image in a Word document has no true vertical position the way a PDF image does — only alignment and, if you add it explicitly, spacing before the image. The fix meant measuring the actual gap in the source PDF and recreating it as spacing before the image in the output document, capped at a sane maximum so a legitimately huge gap couldn't push content onto a spurious extra page.

Bug four: a field that was set correctly and then silently dropped

This one wasn't reported by anyone — it turned up during review of the images fix above. A new flag marking certain images as "footer zone" content (so they'd get the spacing treatment from the bug above) was being set correctly early in the image-processing code, but a later step that rebuilds each image object from an explicit list of fields simply didn't include that new field in the list — so it silently vanished by the time anything downstream tried to read it. Nothing crashed; the flag just quietly stopped existing. The general lesson, worth stating plainly: adding a new field to a data structure isn't finished at the point you set it — it has to be traced all the way to every place that structure gets rebuilt or copied, or it can disappear invisibly at exactly one of those points.

What these four bugs have in common

None of them are exotic edge cases — they're all ordinary documents doing ordinary things (a bulleted list, page numbers, a logo with some space above it) that happen to sit exactly on a boundary a simpler converter's assumptions didn't account for. That's really the whole difficulty of PDF-to-Word conversion in one sentence: not that any single case is hard to imagine, but that a PDF's actual structure is just coordinates and text, and every piece of "obvious" document structure — a bullet, a page number, an image's intended position — has to be reconstructed by inference, and inference has edge cases that only show up against real documents, not clean test files built to demonstrate a feature working.