{"record":{"id":"89b6a22ab8dc78f9","repo":"docling-project/docling","slug":"incompatible-file-format-self-input-format-was-p","errorCode":null,"errorMessage":"Incompatible file format {self.input_format} was passed to ImageDocumentBackend.","messagePattern":"Incompatible file format (.+?) was passed to ImageDocumentBackend\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/image_backend.py","lineNumber":151,"sourceCode":"          the image→PDF conversion and any pypdfium2 usage.\n        - Handles multi-page TIFF by extracting frames eagerly to separate\n          Image objects to keep thread-safety when pages process in parallel.\n    \"\"\"\n\n    def __init__(\n        self,\n        in_doc: InputDocument,\n        path_or_stream: Union[BytesIO, Path],\n        options: Optional[PdfBackendOptions] = None,\n    ):\n        if options is None:\n            options = PdfBackendOptions()\n        # Bypass PdfDocumentBackend.__init__ to avoid image→PDF conversion\n        AbstractDocumentBackend.__init__(self, in_doc, path_or_stream, options)\n        self.options: PdfBackendOptions = options\n\n        if self.input_format not in {InputFormat.IMAGE}:\n            raise RuntimeError(\n                f\"Incompatible file format {self.input_format} was passed to ImageDocumentBackend.\"\n            )\n\n        # Load frames eagerly for thread-safety across pages\n        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\"))","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/image_backend.py#L133-L169","documentation":"ImageDocumentBackend.__init__ raises RuntimeError when in_doc.input_format is anything other than InputFormat.IMAGE. The class deliberately bypasses PdfDocumentBackend.__init__ to avoid image-to-PDF conversion, so it can only serve direct image input; passing PDF or other formats is a caller contract violation.","triggerScenarios":"Constructing ImageDocumentBackend with an InputDocument whose input_format is InputFormat.PDF or another format; usually caused by manually instantiating backends instead of letting the format-registry/dispatch pick the right one.","commonSituations":"Custom pipelines that hardcode a backend class; format-detection bugs that label a PDF as IMAGE; refactors that swap backend classes without updating the InputDocument format.","solutions":["Let DocumentConverter / the backend registry choose the backend from the detected format","If constructing manually, ensure InputDocument.input_format == InputFormat.IMAGE","Use PdfDocumentBackend (or the appropriate backend) for non-image input"],"exampleFix":"# before\nbackend = ImageDocumentBackend(in_doc, path)  # in_doc.input_format == InputFormat.PDF\n\n# after\nassert in_doc.input_format == InputFormat.IMAGE\nbackend = ImageDocumentBackend(in_doc, path)","handlingStrategy":"validation","validationCode":"from docling.datamodel.base_models import InputFormat\n\nassert in_doc.input_format == InputFormat.IMAGE, (\n    f'ImageDocumentBackend requires IMAGE input, got {in_doc.input_format}'\n)","typeGuard":"def accepts_image_backend(in_doc) -> bool:\n    return in_doc.input_format == InputFormat.IMAGE","tryCatchPattern":null,"preventionTips":["Prefer the backend registry / DocumentConverter over manual backend instantiation","Keep InputDocument.format and backend class in sync in custom pipelines"],"tags":["image","api-contract","format-mismatch"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}