PDF

Fix qpdf "expected N 0 obj" and "expected endobj" Errors

Error message: expected N 0 obj

Fix qpdf “expected N 0 obj” and “expected endobj” Errors

You ran a PDF through qpdf --check (or another qpdf operation) and saw warnings like expected N 0 obj or expected endobj, often alongside file is damaged and Attempting to reconstruct cross-reference table. The good news: in almost every case where you see these warnings, qpdf is telling you it has already fixed the problem in memory and only needs one more step to write you a clean file. Exit code 3 means the recovery worked. Exit code 2 means it didn’t.

Quick fix

If you ran --check to diagnose, the actual repair is one command:

qpdf --linearize input.pdf output.pdf

--linearize rebuilds the cross-reference table from scratch and writes a clean output file. The warnings you saw on --check will appear again during this run — they’re informational, not failures. Look at the final lines:

  • qpdf: operation succeeded with warnings; resulting file may have some problems — exit code 3. The output is usually fine. Open it and inspect.
  • qpdf: file ... is damaged and cannot be processed — exit code 2. Structural recovery failed; escalate to the alternatives below.

See the complete guide to qpdf for installation and other operations.

A more conservative alternative

If the original file already opens in some readers (Acrobat tolerates these warnings; PDF-XChange and stricter readers don’t), and you want a minimally-modified output, use:

qpdf --object-streams=preserve input.pdf output.pdf

This rebuilds the xref without linearizing the file, producing a smaller change to the byte structure. The output passes through stricter readers without losing anything that linearization would also have preserved.

If qpdf reports it cannot process the file

When exit code 2 is returned, the structural damage is more severe than missing object markers — the recovery scan couldn’t find enough valid objects to rebuild from. Try in order:

  1. Re-obtain the file from source. If the PDF came from a download, email, or transfer, the most common cause of severe damage is that the file is incomplete. A fresh copy often opens without any repair tooling.

  2. Open in Adobe Acrobat. Acrobat’s repair behaviour is more aggressive than qpdf’s in some failure modes. Open the file in Acrobat or Acrobat Reader; if it displays, save through File > Save As in Acrobat Pro to produce a clean file.

  3. Try Ghostscript re-rendering. Ghostscript re-interprets the PDF rather than parsing its structure, which sometimes succeeds on files qpdf can’t. Be aware that this approach commonly loses form fields, annotations, digital signatures, and bookmarks. See the PDF repair complete guide for the full caveats.

Why this happens

A PDF stores its content as numbered objects, each with a strict syntax: a header line of the form N 0 obj, the object’s contents, and a closing endobj marker. The cross-reference table records the byte offset of each object’s obj header.

When qpdf reports expected N 0 obj, it followed an offset from the xref to that location and found something other than the expected header — often a few bytes of stream content, a comment, or junk left over from a botched edit. When it reports expected endobj, it found the header correctly but the closing marker didn’t appear where the object’s declared length said it should.

These warnings nearly always come from one of these causes:

  • Truncated files. A download or copy that ended partway through the file leaves objects with valid headers but missing endings.
  • Files modified by tools that wrote bad incremental updates. Some PDF editors (especially older or web-based ones) append updates without correctly recording new offsets, leaving the xref pointing to wrong locations.
  • Files generated by non-spec-compliant PDF producers. Some libraries emit objects that work in Acrobat (which is permissive) but fail validation in stricter parsers.
  • Bit-flips from storage media or transit. Rare but real, especially on aging hard drives or cheap flash memory.

The Attempting to reconstruct cross-reference table line that usually follows tells you qpdf has switched from trusting the xref to scanning the file directly for object markers. If it finds enough of them, it builds a new xref from scratch and the file is recoverable. The warnings remain in the output because they describe what qpdf had to ignore.

On the rare case where linearization makes things worse

In rare cases, qpdf --linearize on an already-clean file with unusual content can introduce parse warnings the original didn’t have. This happens with files that use specific edge cases of the PDF spec — most reported instances involve files generated by pdflatex for slide presentations with embedded screen captures. The output is still readable but qpdf now reports the same warnings on the linearized version.

If you only ran qpdf to check a file that was already opening cleanly elsewhere, the warnings may simply reflect a non-spec construction that worked anyway. Confirm by opening the original in Acrobat — if it opens cleanly there, the file is structurally fine for most purposes and you don’t need to “fix” it. The warnings are a strict reading of the spec, not always a sign of corruption.

Preventing this in future

Save downloads to disk fully before processing them. Tools that operate on streamed or partially-downloaded files routinely produce these warnings on otherwise-fine documents.

For PDF generation pipelines you control, run qpdf --check against output samples periodically. It’s a fast way to catch a producer that’s quietly emitting non-compliant files before the problem reaches users.

For batch workflows that operate on many PDFs, normalize through qpdf or pikepdf as a first step. Both rewrite the file with a clean structure, which means downstream tools never see the malformed-but-tolerable shapes that strict parsers reject.

If qpdf instead reports Cross-reference table not found, the problem is one level higher — the xref itself is missing, not just the objects it points to. The PDF-XChange-specific Structure 40 error is the same underlying problem from a different reader’s perspective. The PDF repair complete guide covers the architecture in more depth.

Last verified: April 2026