`pymupdf.mupdf.FzErrorFormat: code=7: cannot find object in xref` error encountered after version `1.25.3`

[bhaskarbharat]

Description of the bug

Hi Team. Based on some criteria, I have written a script that removed some text, overlapping images, and vector graphics from a PDF.
Two days ago, we upgraded the PyMuPDF version on our server from 1.25.3 to 1.25.4. Today, we received the following Error Exception raised corresponding to a PDF file:

[ERROR] 2025-04-01 14:58:43 Example.pdf - sample Traceback (most recent call last):
  File "/Users/user/Documents/sample.py", line 45, in sample_func
    doc.ez_save(dst_pdf)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 4223, in ez_save
    return self.save(
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 5584, in save
    mupdf.pdf_write_document(pdf, out, opts)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/mupdf.py", line 53942, in pdf_write_document
    return _mupdf.pdf_write_document(doc, out, opts)
pymupdf.mupdf.FzErrorFormat: code=7: cannot find object in xref (21 0 R)

Today, I checked that a new version of PyMuPDF has released, that is, 1.25.5. I upgraded my server to that version to see if the error goes away, but it persisted. I also experimented with different save parameters and their values to see if the error resolves (an example below), but the same error persisted.

# doc.ez_save(dst_pdf)
doc.save(dst_pdf, garbage=4, clean=True, deflate=True, use_objstms=1)

I then downgraded the version to 1.25.3. The script execution resulted in the following error message but no Error Exception was raised and the file got saved successfully:

MuPDF error: format error: cannot find object in xref (21 0 R)

How to reproduce the bug

Sharing below my example script for your reference. I have changed the script to keep the broad logic same. The script does contain all the PyMuPDF methods that I have used in the original script.

import logging
from io import BytesIO
import fitz

logger = logging.getLogger(__file__)

TARGET_TEXT = "xyz"

def sample_func(src_pdf):
    if isinstance(src_pdf, BytesIO):
        # if input_pdf is a BytesIO object
        src_pdf.seek(0)
        doc = fitz.open(stream=src_pdf, filetype="pdf")
    elif isinstance(src_pdf, str):
        doc = fitz.open(src_pdf)

    for page_num in range(len(doc)):
        # Load the page
        page = doc.load_page(page_num)
        logger.info(f"page_num: {page_num + 1}")

        text_blocks = page.get_text("dict")["blocks"]
        for block in text_blocks:
            if block["type"] == 0:  # text block
                for line in block["lines"]:
                    for span in line["spans"]:                            
                        text_rect = fitz.Rect(span['bbox'])
                        logger.debug(f"span: {span}")
                                
                        # Extract text within the specified rectangle
                        text = page.get_text("text", clip=text_rect).strip()

                        if text == TARGET_TEXT:
                            # Create redaction annotation
                            redact_annot = page.add_redact_annot(text_rect)

                            # images=2 blanks out overlapping pixels
                            # graphics=2 removes any overlapping vector graphics
                            # text=0 removes all characters whose boundary box overlaps any redaction rectangle
                            page.apply_redactions(images=2, graphics=2, text=0)


    # Save the modified document
    dst_pdf = BytesIO()
    doc.ez_save(dst_pdf)
    
    doc.close()

    dst_pdf.seek(0)
    return dst_pdf.read()

Following is the Error Exception raised on running the above script:

[ERROR] 2025-04-01 14:58:43 Example.pdf - sample Traceback (most recent call last):
  File "/Users/user/Documents/sample.py", line 45, in sample_func
    doc.ez_save(dst_pdf)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 4223, in ez_save
    return self.save(
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 5584, in save
    mupdf.pdf_write_document(pdf, out, opts)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/mupdf.py", line 53942, in pdf_write_document
    return _mupdf.pdf_write_document(doc, out, opts)
pymupdf.mupdf.FzErrorFormat: code=7: cannot find object in xref (21 0 R)

PyMuPDF version

1.25.5

Operating system

Linux

Python version

3.10

[JorjMcKie]

Please always provide a reproducing file!

Otherwise, this probably is a justified message indicating that there exist cross reference numbers which point to non-existent object definitions in a PDF with object statement compression.

[bhaskarbharat]

Thanks for the response @JorjMcKie

I understand that a reproducing file always helps but I am afraid that I won't be able to share the said PDF as it contains confidential client information.

The main motive behind raising this issue was to highlight that the original script when processed the same PDF resulted in different behaviours depending on PyMuPDF versions:

1. In case of version 1.25.3, the script execution resulted in the following error message but no Error Exception was raised and the file got saved successfully:

MuPDF error: format error: cannot find object in xref (21 0 R)

2. In case of version 1.25.4 and 1.25.5, the script execution resulted in the following Error Exception being raised and hence failure of file save operation. Additionally, I could not avoid/resolve the error even after experimenting with different save parameters and their values as mentioned previously (even with garbage=0).

[ERROR] 2025-04-01 14:58:43 Example.pdf - sample Traceback (most recent call last):
  File "/Users/user/Documents/sample.py", line 45, in sample_func
    doc.ez_save(dst_pdf)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 4223, in ez_save
    return self.save(
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 5584, in save
    mupdf.pdf_write_document(pdf, out, opts)
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/mupdf.py", line 53942, in pdf_write_document
    return _mupdf.pdf_write_document(doc, out, opts)
pymupdf.mupdf.FzErrorFormat: code=7: cannot find object in xref (21 0 R)

The file output that I receive in case of version 1.25.3 is good enough for my case. Therefore, for the time being I have downgraded the PyMuPDF version to 1.25.3 on server side.

I need your help in understanding if there's a way I can avoid the Error Exception being raised in case of versions 1.25.4 and 1.25.5 so that the file save operation succeeds and provide the same output file as in case of version 1.25.3 even if this file is not fully repaired and contains some broken cross references?

[JorjMcKie]

Well, if you cannot share the file, then only reduced options remain for us to help you.

• You could insert a loop through the PDF's xref table and deal with broken items one by one.
• Or you pre-process the PDF with the full arsenal of garbage collection and repair options.

E.g. the following extracts all object definitions and provides an empty object in case of problems.

for xref in range(1, doc.xref_length()):
    try:
        _ = doc.xref_object(xref)
    except:
        doc.update_object(xref, "<<>>")

Note: Edited the first line of the above snippet! We must skip the first item of the cross reference table.

[yang-521]

I had the same problem

[yang-521]

[yang-521]

I tried to upload my sample, but the file was too large and it didn't seem to succeed

[bhaskarbharat]

@JorjMcKie I incorporated the code that you provided just before the save operation as shown below:

import logging
from io import BytesIO
import fitz

logger = logging.getLogger(__file__)

TARGET_TEXT = "xyz"

def sample_func(src_pdf):
    if isinstance(src_pdf, BytesIO):
        # if input_pdf is a BytesIO object
        src_pdf.seek(0)
        doc = fitz.open(stream=src_pdf, filetype="pdf")
    elif isinstance(src_pdf, str):
        doc = fitz.open(src_pdf)

    for page_num in range(len(doc)):
        # Load the page
        page = doc.load_page(page_num)
        logger.info(f"page_num: {page_num + 1}")

        text_blocks = page.get_text("dict")["blocks"]
        for block in text_blocks:
            if block["type"] == 0:  # text block
                for line in block["lines"]:
                    for span in line["spans"]:                            
                        text_rect = fitz.Rect(span['bbox'])
                        logger.debug(f"span: {span}")
                                
                        # Extract text within the specified rectangle
                        text = page.get_text("text", clip=text_rect).strip()

                        if text == TARGET_TEXT:
                            # Create redaction annotation
                            redact_annot = page.add_redact_annot(text_rect)

                            # images=2 blanks out overlapping pixels
                            # graphics=2 removes any overlapping vector graphics
                            # text=0 removes all characters whose boundary box overlaps any redaction rectangle
                            page.apply_redactions(images=2, graphics=2, text=0)

    for xref in range(doc.xref_length()):
        try:
            _ = doc.xref_object(xref)
        except:
            doc.update_object(xref, "<<>>")

    # Save the modified document
    dst_pdf = BytesIO()
    doc.ez_save(dst_pdf)
    
    doc.close()

    dst_pdf.seek(0)
    return dst_pdf.read()

Following is the Error Exception raised on running the above script:

Traceback (most recent call last):
  File "/Users/user/Documents/sample.py", line 46, in sample_func
    doc.update_object(xref, "<<>>")
  File "/Users/user/miniconda3/envs/test4_env/lib/python3.10/site-packages/pymupdf/__init__.py", line 5829, in update_object
    RAISEPY("bad xref", MSG_BAD_XREF, PyExc_ValueError)
TypeError: RAISEPY() takes 2 positional arguments but 3 were given

I tried going through the documentation to understand how to resolve this new error but couldn't find a solution. Could you please help me with this?

[JorjMcKie]

This line was specified wrong, sorry: for xref in range(doc.xref_length()):.
It should have been for xref in range(1, doc.xref_length()):!!!

[samiy803]

I'm also running into the same error. Seems like 1.25.3 is working and will use that for now. Also similar to @bhaskarbharat, I cannot provide a sample file due to confidentiality. However, simply reading the PDF and saving it is enough to reproduce the error:

import fitz
doc = fitz.open("some_pdf.pdf")
doc.save("test_pdf.pdf")

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/sami/.pyenv/versions/3.10.0/lib/python3.10/site-packages/pymupdf/__init__.py", line 5580, in save
    mupdf.pdf_save_document(pdf, filename, opts)
  File "/Users/sami/.pyenv/versions/3.10.0/lib/python3.10/site-packages/pymupdf/mupdf.py", line 53284, in pdf_save_document
    return _mupdf.pdf_save_document(doc, filename, opts)
pymupdf.mupdf.FzErrorFormat: code=7: cannot find object in xref (4689 0 R)

Perhaps there should be an argument to skip non-existent xrefs instead of the default behavior of raising an exception?

[JorjMcKie]

As I wrote above:
Adding the same type of post again and again without providing a reproducing file in one single case will not help anyone.
Please somebody at least try this with such a file:

import fitz
doc = fitz.open("some_pdf.pdf")
for xref in range(1, doc.xref_length():
    try:
        _ = doc.xref_object(xref)
    except:
        doc.update_object(xref, "<<>>")
doc.save("test_pdf.pdf")

And report back here how this works.
Or - preferably - attach an as small as possible example file.
Thank you.

[samiy803]

@JorjMcKie Can confirm, your solution does work with my PDF.

[JorjMcKie]

@JorjMcKie Can confirm, your solution does work with my PDF.

OMG thank you!