BASALT · JOURNAL
Recovering a damaged PDF
Most PDF damage is in the cross reference table rather than the content, which is why repair works more often than people expect.
Diagnose first
qpdf --check document.pdfThis reports structural problems without rendering. The output tells you whether the damage is recoverable bookkeeping or missing content.
The repair that usually works
qpdf --replace-input --qdf --object-streams=disable broken.pdfThis rebuilds the cross reference table by scanning the file for objects, which recovers documents whose index is broken but whose content is intact.
Work on a copy. Repair is not always lossless and you want the original if it fails.
Recovering pages individually
If the whole document will not open, individual pages sometimes will:
qpdf --pages broken.pdf 1-10 -- part1.pdfWorking through ranges finds where the damage is. A document with one bad page can often be reassembled without it.
When content is genuinely gone
If the file was truncated, the missing bytes are missing and no tool recovers them. A file noticeably smaller than expected is usually a failed download, and re-downloading is faster than any repair.
The most common causes
An interrupted transfer, by a wide margin. Try downloading again before anything else.
A file sent through a system that treated it as text rather than binary, which corrupts it throughout. Recovery here is unlikely.
Storage failure, in which case check other files too.
Preventing repeats
Compare checksums for anything important that moves between systems. shasum -a 256 on both ends takes seconds and tells you definitively whether the file arrived intact, rather than discovering it weeks later when someone tries to open it.
Frequently asked questions
How do I repair a corrupted PDF?
Run qpdf --check first to see what is wrong, then qpdf --replace-input --qdf --object-streams=disable on a copy, which rebuilds the cross reference table by scanning for objects. That recovers documents whose index is broken but whose content is intact.
Can any PDF be recovered?
No. If the file was truncated the missing bytes are gone and no tool recreates them. A file noticeably smaller than expected is usually a failed download, and re-downloading is faster than attempting repair.
What causes PDF corruption most often?
Interrupted transfers by a wide margin, followed by files sent through systems that treat them as text rather than binary, and storage failures.
How do I recover part of a broken PDF?
Extract page ranges with qpdf --pages broken.pdf 1-10 -- part1.pdf. Working through ranges locates the damage, and a document with one bad page can often be reassembled without it.
Doing it in Basalt
Basalt is a native macOS PDF toolkit: eighteen tools in one window covering merge, split, page organisation, compression, OCR, passwords, Bates numbering, forms, signing, watermarks and comparison. Every file is processed on your Mac, and the engine that opens documents holds no network entitlement at all, which macOS enforces at the code-signature level. Redaction destroys content rather than covering it, and an independent verifier proves the material is gone before a file is written. A one time $29 licence covers up to three Macs, free for the first 24 hours. basaltformac.com, or brew install --cask chipmunk1101/tap/basalt.
Redaction that proves itself
Basalt destroys the content you mark, then re-opens the file it wrote and proves the content is gone before it saves anything. Your documents never leave your Mac.