docling-project/docling · error · RuntimeError

Invalid HTML document.

Error message

Invalid HTML document.

What it means

HTMLDocumentBackend.convert() raises RuntimeError('Invalid HTML document.') when is_valid() returns false, i.e. self.soup is None because init never built a parse tree. It is the standard guard that prevents convert() from operating on an uninitialized backend.

Source

Thrown at docling/backend/html_backend.py:508

    def supports_pagination(cls) -> bool:
        return False

    @override
    def unload(self):
        if isinstance(self.path_or_stream, BytesIO):
            self.path_or_stream.close()
        self.path_or_stream = None

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

    @override
    def convert(self) -> DoclingDocument:
        _log.debug("Starting HTML conversion...")
        if not self.is_valid():
            raise RuntimeError("Invalid HTML document.")

        origin = DocumentOrigin(
            filename=self.file.name or "file",
            mimetype="text/html",
            binary_hash=self.document_hash,
        )
        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)

        if cast(HTMLBackendOptions, self.options).render_page:
            self._render_with_browser()
            if self._rendered_html:
                self.soup = BeautifulSoup(self._rendered_html, "html.parser")

        if self._rendered_page_images and self._rendered_page_size:
            render_dpi = cast(HTMLBackendOptions, self.options).render_dpi
            for page_no, page_image in enumerate(self._rendered_page_images, start=1):
                doc.add_page(
                    page_no=page_no,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check backend.is_valid() before convert()
2. Let __init__ exceptions terminate the conversion attempt instead of catching and continuing
3. Rebuild the backend from the original source for each retry

Example fix

# before
doc = backend.convert()

# after
if not backend.is_valid():
    raise ValueError('HTML backend not initialized; check input and init errors')
doc = backend.convert()

if not backend.is_valid():
    raise ValueError('HTML backend not initialized; check init errors first')

When it happens

Trigger: Calling convert() after __init__ failed but the exception was caught upstream; any flow where the BeautifulSoup tree was never created.

Common situations: Broad except blocks around backend construction followed by unconditional convert(); orchestration frameworks retrying convert() on the same broken object.

Related errors

• Cannot convert doc with {self.document_hash} because the bac
• Cannot convert EPUB with hash {self.document_hash} because t
• Cannot convert doc with {self.document_hash} because the bac
• The 'beautifulsoup4' package is required to process HTML fil
• Could not initialize HTML backend for file with hash {self.d

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