# Fix PyMuPDF "cannot open broken document" on a scanned NDA

## TL;DR
PyMuPDF is strict about PDF structure and refuses files with damaged cross-reference tables that lenient viewers open without complaint. Repair the file with qpdf or mutool clean to rebuild the xref, then open the repaired copy with PyMuPDF.

```text
cannot open broken document
```

## Steps
1. Diagnose: run qpdf --check file.pdf.
   Expected: xref table or trailer errors, confirming structural damage rather than a content problem.
2. Repair with qpdf --replace-input file.pdf (or write to a new file to preserve the original), or with mutool clean -d input.pdf output.pdf.
   Expected: clean exit; qpdf --check passes afterward.
3. Open the repaired file with PyMuPDF as before.
   Expected: the document opens with the correct page count.
4. If repair tools fail, re-render the PDF through Ghostscript into a fresh file and open that.
   Expected: a structurally clean file PyMuPDF accepts.

## Use this when
- PyMuPDF raises "cannot open broken document" on a scan that opens in a viewer
- Scanned NDAs or exhibits fail at open time in your pipeline
- The file passed through a scanner, email, or merge tool before reaching you

## Not for this skill when
- The file is password-protected (supply the password first)
- PyMuPDF opens the file but text extraction is wrong (that's a font/OCR problem)
- All files fail to open (that's an install/environment problem)

## Variant phrasings
### pymupdf fitz open broken pdf error
Same repair path; fitz is just the import name for PyMuPDF.
### repair pdf xref table qpdf mutool clean
qpdf --check diagnoses, qpdf or mutool clean rebuilds.
### scanned pdf won't open in python but opens in viewer
Viewers tolerate structural damage; parsers need the repair step.

## Why it happens
Scanners and email gateways frequently damage the cross-reference table or trailer while leaving page content intact. Lenient viewers reconstruct the structure on the fly; PyMuPDF validates it and refuses. The content is almost always fine; only the indexing structure needs rebuilding.

## Edge cases
- Password-protected scans need unlocking before repair tools can rebuild the xref.
- Keep the original file for audit; repair to a copy in pipelines.
- Incremental scanner annotations (stamps, redactions) can re-damage the xref; repair after all annotations are applied.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D7MLOTIRzOB1kLgZ1XMt-Q
