{"record":{"id":"3bad6352c9255b45","repo":"docling-project/docling","slug":"cannot-convert-epub-with-hash-self-document-hash","errorCode":null,"errorMessage":"Cannot convert EPUB with hash {self.document_hash} because the backend failed to init.","messagePattern":"Cannot convert EPUB with hash (.+?) because the backend failed to init\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/epub_backend.py","lineNumber":345,"sourceCode":"    def supports_pagination(cls) -> bool:\n        return False\n\n    @classmethod\n    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.EPUB}\n\n    @override\n    def convert(self) -> DoclingDocument:\n        \"\"\"Convert the EPUB file to a DoclingDocument.\n\n        This method extracts all content files from the EPUB and processes\n        them sequentially using the HTMLDocumentBackend.\n        \"\"\"\n        _log.debug(\"Converting EPUB...\")\n\n        if not self.is_valid() or not self.epub_zip:\n            raise RuntimeError(\n                f\"Cannot convert EPUB with hash {self.document_hash} because the backend failed to init.\"\n            )\n\n        # Create document origin\n        origin = DocumentOrigin(\n            filename=self.file.name or \"file\",\n            mimetype=\"application/epub+zip\",\n            binary_hash=self.document_hash,\n        )\n\n        # Initialize the main document\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n\n        # Extract EPUB to temporary directory if images need to be fetched\n        # This allows the HTML backend to access images from the filesystem\n        if self.options.fetch_images and self.options.enable_local_fetch:\n            try:\n                self.temp_dir = Path(tempfile.mkdtemp(prefix=\"docling_epub_\"))","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/epub_backend.py#L327-L363","documentation":"EpubDocumentBackend.convert() raises RuntimeError when is_valid() is false or epub_zip is None — i.e. the backend never completed structural parsing. Like other backends, EPUB marks validity only after a successful init, and convert() refuses to run on an uninitialized backend.","triggerScenarios":"Calling convert() on an EPUB backend whose __init__ failed (invalid zip) through a code path that suppressed the init exception; also any state where content_files was never populated.","commonSituations":"Error-handling layers that log-but-continue after DocumentLoadError and later call convert(); reusing backend instances across retries.","solutions":["Check backend.is_valid() before calling convert()","Abort processing when __init__ raises instead of proceeding","Use a fresh backend per attempt"],"exampleFix":"# before\ndoc = backend.convert()\n\n# after\nif not backend.is_valid():\n    raise ValueError('EPUB structure was not parsed; input is likely invalid')\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"if not backend.is_valid():\n    raise ValueError('EPUB backend not initialized; input likely invalid')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Stop processing when EPUB init raises; do not continue to convert()","Rebuild backends from source on retry"],"tags":["epub","state-machine","lifecycle"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}