{"record":{"id":"8daa7dbec0399166","repo":"docling-project/docling","slug":"could-not-initialize-epub-backend-for-file-with-ha","errorCode":null,"errorMessage":"Could not initialize EPUB backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize EPUB backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/epub_backend.py","lineNumber":80,"sourceCode":"        self.temp_dir: Path | None = None\n\n        try:\n            # Open the EPUB file as a ZIP archive\n            if isinstance(self.path_or_stream, BytesIO):\n                self.epub_zip = ZipFile(self.path_or_stream, \"r\")\n            elif isinstance(self.path_or_stream, Path):\n                self.epub_zip = ZipFile(self.path_or_stream, \"r\")\n            else:\n                raise ValueError(\"path_or_stream must be BytesIO or Path\")\n\n            # Parse the EPUB structure\n            self._parse_epub_structure()\n            self.valid = True\n\n            _log.debug(f\"Found {len(self.content_files)} content files in EPUB\")\n        except Exception as e:\n            _log.error(f\"Failed to initialize EPUB backend: {e}\")\n            raise DocumentLoadError(\n                f\"Could not initialize EPUB backend for file with hash {self.document_hash}.\"\n            ) from e\n\n    def _parse_epub_structure(self):\n        \"\"\"Parse the EPUB structure to find content files and metadata.\"\"\"\n        if not self.epub_zip:\n            return\n\n        # Read container.xml to find the content.opf file\n        try:\n            container_data = self.epub_zip.read(\"META-INF/container.xml\")\n            container_root = ET.fromstring(container_data)\n\n            # Find the content.opf path\n            ns = {\"container\": \"urn:oasis:names:tc:opendocument:xmlns:container\"}\n            rootfile = container_root.find(\".//container:rootfile\", ns)\n\n            if rootfile is None:","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/epub_backend.py#L62-L98","documentation":"EpubDocumentBackend.__init__ wraps every exception raised while opening the EPUB as a ZipFile and parsing its structure (_parse_epub_structure) into DocumentLoadError. Typical underlying causes: not a zip at all, missing META-INF/container.xml, corrupt zip entries, or an invalid OPF; the original exception is chained as __cause__ and also logged.","triggerScenarios":"Passing a file with an .epub extension that is not a valid EPUB zip; truncated downloads; EPUBs without META-INF/container.xml; permission errors opening the path.","commonSituations":"Ingesting user uploads where the extension lies about content; partially downloaded files; EPUBs produced by niche exporters that omit container.xml.","solutions":["Inspect exc.__cause__ (BadZipFile, ParseError, KeyError for missing zip entries) to classify the failure","Pre-check with zipfile.ZipFile(path).testzip() and verify 'META-INF/container.xml' in namelist()","Re-download or repair the EPUB source"],"exampleFix":"# before\nres = converter.convert(epub_path)\n\n# after\nimport zipfile\nwith zipfile.ZipFile(epub_path) as zf:\n    assert 'META-INF/container.xml' in zf.namelist(), 'not a valid EPUB'\nres = converter.convert(epub_path)","handlingStrategy":"try-catch","validationCode":"import zipfile\n\nwith zipfile.ZipFile(epub_path) as zf:\n    bad = zf.testzip()\n    assert bad is None, f'corrupt zip entry: {bad}'\n    assert 'META-INF/container.xml' in zf.namelist(), 'not a valid EPUB (no container.xml)'","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(epub_path)\nexcept DocumentLoadError as exc:\n    log.warning('bad EPUB %s: %s', epub_path, exc.__cause__ or exc)\n    quarantine(epub_path)","preventionTips":["Validate zip integrity and container.xml presence for user-uploaded EPUBs","Check exc.__cause__ to classify BadZipFile vs missing-entry errors"],"tags":["epub","zip","corrupt-input","parsing"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}