{"record":{"id":"fb12e8a0b76c3e77","repo":"docling-project/docling","slug":"could-not-load-image-for-document-self-file","errorCode":null,"errorMessage":"Could not load image for document {self.file}","messagePattern":"Could not load image for document (.+?)","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/image_backend.py","lineNumber":174,"sourceCode":"        self._frames: List[Image.Image] = []\n        try:\n            with Image.open(self.path_or_stream) as img:  # type: ignore[arg-type]\n                # Handle multi-frame and single-frame images\n                # - multiframe formats: TIFF, GIF, ICO\n                # - singleframe formats: JPEG (.jpg, .jpeg), PNG (.png), BMP, WEBP (unless animated), HEIC\n                frame_count = getattr(img, \"n_frames\", 1)\n\n                if frame_count > 1:\n                    for i in range(frame_count):\n                        img.seek(i)\n                        self._frames.append(img.copy().convert(\"RGB\"))\n                else:\n                    self._frames.append(img.convert(\"RGB\"))\n        except Exception as e:\n            for frame in self._frames:\n                frame.close()\n            self._frames = []\n            raise DocumentLoadError(\n                f\"Could not load image for document {self.file}\"\n            ) from e\n\n    def is_valid(self) -> bool:\n        return len(self._frames) > 0\n\n    def page_count(self) -> int:\n        return len(self._frames)\n\n    def load_page(self, page_no: int) -> _ImagePageBackend:\n        if not (0 <= page_no < len(self._frames)):\n            raise IndexError(f\"Page index out of range: {page_no}\")\n        return _ImagePageBackend(self._frames[page_no], page_no)\n\n    @classmethod\n    def supported_formats(cls) -> set[InputFormat]:\n        # Only IMAGE here; PDF handling remains in PDF-oriented backends\n        return {InputFormat.IMAGE}","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/image_backend.py#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"Ingesting user uploads without validation; HEIC photos from iPhones on an environment without the HEIF plugin; partially transferred files in queues.","solutions":["Pre-validate with PIL: Image.open(...).verify() before handing the file to Docling","Inspect exc.__cause__ to identify the exact Pillow failure","For HEIC, install the required Pillow plugin or convert inputs to JPEG/PNG upstream","Verify Pillow is up to date for the formats you ingest"],"exampleFix":"# before\nres = converter.convert(img_path)  # DocumentLoadError on corrupt file\n\n# after\nfrom PIL import Image\nwith Image.open(img_path) as im:\n    im.verify()  # raises early on truncated/corrupt data\nres = converter.convert(img_path)","handlingStrategy":"try-catch","validationCode":"from PIL import Image\n\nwith Image.open(img_path) as im:\n    im.verify()  # detects truncation/corruption cheaply\n# optional codec check for HEIC inputs:\n# ensure pillow-heif is installed before accepting .heic uploads","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(img_path)\nexcept DocumentLoadError as exc:\n    log.warning('image load failed %s: %s', img_path, exc.__cause__ or exc)\n    quarantine(img_path)","preventionTips":["Verify images with PIL before batch conversion","Install format-specific Pillow plugins (e.g. pillow-heif) for the codecs you accept"],"tags":["image","pillow","corrupt-input","codec"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}