docling-project/docling · error · DocumentLoadError

Could not initialize EPUB backend for file with hash {self.d

Error message

Could not initialize EPUB backend for file with hash {self.document_hash}.

What it means

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.

Source

Thrown at docling/backend/epub_backend.py:80

        self.temp_dir: Path | None = None

        try:
            # Open the EPUB file as a ZIP archive
            if isinstance(self.path_or_stream, BytesIO):
                self.epub_zip = ZipFile(self.path_or_stream, "r")
            elif isinstance(self.path_or_stream, Path):
                self.epub_zip = ZipFile(self.path_or_stream, "r")
            else:
                raise ValueError("path_or_stream must be BytesIO or Path")

            # Parse the EPUB structure
            self._parse_epub_structure()
            self.valid = True

            _log.debug(f"Found {len(self.content_files)} content files in EPUB")
        except Exception as e:
            _log.error(f"Failed to initialize EPUB backend: {e}")
            raise DocumentLoadError(
                f"Could not initialize EPUB backend for file with hash {self.document_hash}."
            ) from e

    def _parse_epub_structure(self):
        """Parse the EPUB structure to find content files and metadata."""
        if not self.epub_zip:
            return

        # Read container.xml to find the content.opf file
        try:
            container_data = self.epub_zip.read("META-INF/container.xml")
            container_root = ET.fromstring(container_data)

            # Find the content.opf path
            ns = {"container": "urn:oasis:names:tc:opendocument:xmlns:container"}
            rootfile = container_root.find(".//container:rootfile", ns)

            if rootfile is None:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Inspect exc.__cause__ (BadZipFile, ParseError, KeyError for missing zip entries) to classify the failure
2. Pre-check with zipfile.ZipFile(path).testzip() and verify 'META-INF/container.xml' in namelist()
3. Re-download or repair the EPUB source

Example fix

# before
res = converter.convert(epub_path)

# after
import zipfile
with zipfile.ZipFile(epub_path) as zf:
    assert 'META-INF/container.xml' in zf.namelist(), 'not a valid EPUB'
res = converter.convert(epub_path)

import zipfile

with zipfile.ZipFile(epub_path) as zf:
    bad = zf.testzip()
    assert bad is None, f'corrupt zip entry: {bad}'
    assert 'META-INF/container.xml' in zf.namelist(), 'not a valid EPUB (no container.xml)'

try:
    result = converter.convert(epub_path)
except DocumentLoadError as exc:
    log.warning('bad EPUB %s: %s', epub_path, exc.__cause__ or exc)
    quarantine(epub_path)

When it happens

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

Common situations: Ingesting user uploads where the extension lies about content; partially downloaded files; EPUBs produced by niche exporters that omit container.xml.

Related errors

• Could not initialize email backend for file with hash {self.
• Cannot convert EPUB with hash {self.document_hash} because t
• Could not initialize HTML backend for file with hash {self.d
• Could not load image for document {self.file}
• Could not initialize JATS backend for file with hash {self.d

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