A cross-reference section is a PDF’s index: it maps each object number to its byte offset in the file, so a reader can jump straight to an object without scanning. Older PDFs use a plain text table; PDF 1.5 and later may compress it into a cross-reference stream instead.
Why this happens
A PDF is read back-to-front. A reader opens the file, jumps to the end, finds `startxref`, and follows it to the cross-reference section — the index that says object 14 lives at byte 90,210. Without it, opening a document would mean scanning the whole file to find anything.
From PDF 1.5 onward that index can take two forms. The classic form is a plain text table you can read in any editor. The newer form compresses it into a cross-reference stream, which is smaller and lets objects be packed into object streams. Both are correct; they are simply different, and code that assumes one will produce a broken file on the other.
This is invisible to you right up until an editor writes an index your reader cannot follow — at which point the document does not open at all, which is a worse outcome than any layout problem.
How Online PDF Edits handles it
Our incremental save appends a new cross-reference section pointing at the objects it just wrote. That path currently supports classic cross-reference tables.
If a file uses a cross-reference stream, we detect it before writing and refuse the edit with a clear message. It would be easy to append a table to such a file and return something that looks fine; it would also produce a document some readers cannot open. A refusal you can act on beats a file that fails silently in someone else’s hands.
The specifics
| How a reader finds the index | The startxref offset at the end of the file |
|---|---|
| Classic table | Supported for incremental append |
| Cross-reference stream (PDF 1.5+) | Detected and refused, with a clear error |
| Behaviour on refusal | No file is produced — never a half-written PDF |
Limitations
- Appending to a cross-reference stream original is not implemented. Those documents return an error rather than an edit.
- This is a deliberate boundary, not an oversight: writing the wrong index shape produces files that fail to open, which is the one failure worse than refusing.
Don’t take our word for any of this. Edit the sample invoice, export it, then select the line you changed and copy it — you should get your new wording, not the old. Compare the export against the original and see what moved.
Every claim in this reference is written from the code that implements it, and every number is measured rather than estimated. The parts you can verify without trusting us are the ones we put in front of you.