docling-project/docling · error · DocumentLoadError

Could not load image for document {self.file}

Error message

Could not load image for document {self.file}

What it means

ImageDocumentBackend.__init__ eagerly loads all PIL frames (for thread-safety across pages) and wraps any exception from Image.open/seek/convert into DocumentLoadError, closing already-loaded frames first. Underlying causes include corrupt images, formats PIL cannot identify, unsupported codecs (e.g. HEIC without plugin), and unreadable files; the cause is chained.

Source

Thrown at docling/backend/image_backend.py:174

        self._frames: List[Image.Image] = []
        try:
            with Image.open(self.path_or_stream) as img:  # type: ignore[arg-type]
                # Handle multi-frame and single-frame images
                # - multiframe formats: TIFF, GIF, ICO
                # - singleframe formats: JPEG (.jpg, .jpeg), PNG (.png), BMP, WEBP (unless animated), HEIC
                frame_count = getattr(img, "n_frames", 1)

                if frame_count > 1:
                    for i in range(frame_count):
                        img.seek(i)
                        self._frames.append(img.copy().convert("RGB"))
                else:
                    self._frames.append(img.convert("RGB"))
        except Exception as e:
            for frame in self._frames:
                frame.close()
            self._frames = []
            raise DocumentLoadError(
                f"Could not load image for document {self.file}"
            ) from e

    def is_valid(self) -> bool:
        return len(self._frames) > 0

    def page_count(self) -> int:
        return len(self._frames)

    def load_page(self, page_no: int) -> _ImagePageBackend:
        if not (0 <= page_no < len(self._frames)):
            raise IndexError(f"Page index out of range: {page_no}")
        return _ImagePageBackend(self._frames[page_no], page_no)

    @classmethod
    def supported_formats(cls) -> set[InputFormat]:
        # Only IMAGE here; PDF handling remains in PDF-oriented backends
        return {InputFormat.IMAGE}

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pre-validate with PIL: Image.open(...).verify() before handing the file to Docling
2. Inspect exc.__cause__ to identify the exact Pillow failure
3. For HEIC, install the required Pillow plugin or convert inputs to JPEG/PNG upstream
4. Verify Pillow is up to date for the formats you ingest

Example fix

# before
res = converter.convert(img_path)  # DocumentLoadError on corrupt file

# after
from PIL import Image
with Image.open(img_path) as im:
    im.verify()  # raises early on truncated/corrupt data
res = converter.convert(img_path)

from PIL import Image

with Image.open(img_path) as im:
    im.verify()  # detects truncation/corruption cheaply
# optional codec check for HEIC inputs:
# ensure pillow-heif is installed before accepting .heic uploads

try:
    result = converter.convert(img_path)
except DocumentLoadError as exc:
    log.warning('image load failed %s: %s', img_path, exc.__cause__ or exc)
    quarantine(img_path)

When it happens

Trigger: Passing a truncated or zero-byte image; a format Pillow cannot decode (HEIC without pillow-heif, exotic TIFF variants); permission/I-O errors on the path; images whose frames fail mid-seek in multi-frame TIFF/GIF.

Common situations: Ingesting user uploads without validation; HEIC photos from iPhones on an environment without the HEIF plugin; partially transferred files in queues.

Related errors

• Unknown EBCDIC codec {encoding!r}.
• Could not initialize email backend for file with hash {self.
• Could not initialize EPUB backend for file with hash {self.d
• Incompatible file format {self.input_format} was passed to I
• Page index out of range: {page_no}

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/fb12e8a0b76c3e77. Report an issue: GitHub.