docling-project/docling · error · RuntimeError

Cannot convert EPUB with hash {self.document_hash} because t

Error message

Cannot convert EPUB with hash {self.document_hash} because the backend failed to init.

What it means

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.

Source

Thrown at docling/backend/epub_backend.py:345

    def supports_pagination(cls) -> bool:
        return False

    @classmethod
    @override
    def supported_formats(cls) -> set[InputFormat]:
        return {InputFormat.EPUB}

    @override
    def convert(self) -> DoclingDocument:
        """Convert the EPUB file to a DoclingDocument.

        This method extracts all content files from the EPUB and processes
        them sequentially using the HTMLDocumentBackend.
        """
        _log.debug("Converting EPUB...")

        if not self.is_valid() or not self.epub_zip:
            raise RuntimeError(
                f"Cannot convert EPUB with hash {self.document_hash} because the backend failed to init."
            )

        # Create document origin
        origin = DocumentOrigin(
            filename=self.file.name or "file",
            mimetype="application/epub+zip",
            binary_hash=self.document_hash,
        )

        # Initialize the main document
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)

        # Extract EPUB to temporary directory if images need to be fetched
        # This allows the HTML backend to access images from the filesystem
        if self.options.fetch_images and self.options.enable_local_fetch:
            try:
                self.temp_dir = Path(tempfile.mkdtemp(prefix="docling_epub_"))

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() before calling convert()
2. Abort processing when __init__ raises instead of proceeding
3. Use a fresh backend per attempt

Example fix

# before
doc = backend.convert()

# after
if not backend.is_valid():
    raise ValueError('EPUB structure was not parsed; input is likely invalid')
doc = backend.convert()

if not backend.is_valid():
    raise ValueError('EPUB backend not initialized; input likely invalid')

When it happens

Trigger: 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.

Common situations: Error-handling layers that log-but-continue after DocumentLoadError and later call convert(); reusing backend instances across retries.

Related errors

• Cannot convert doc with {self.document_hash} because the bac
• Invalid HTML document.
• Cannot convert doc with {self.document_hash} because the bac
• Could not initialize EPUB backend for file with hash {self.d
• KServe v2 client is not initialized.

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