{"record":{"id":"a59366a1fde32ab0","repo":"docling-project/docling","slug":"invalid-html-document","errorCode":null,"errorMessage":"Invalid HTML document.","messagePattern":"Invalid HTML document\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/html_backend.py","lineNumber":508,"sourceCode":"    def supports_pagination(cls) -> bool:\n        return False\n\n    @override\n    def unload(self):\n        if isinstance(self.path_or_stream, BytesIO):\n            self.path_or_stream.close()\n        self.path_or_stream = None\n\n    @classmethod\n    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.HTML}\n\n    @override\n    def convert(self) -> DoclingDocument:\n        _log.debug(\"Starting HTML conversion...\")\n        if not self.is_valid():\n            raise RuntimeError(\"Invalid HTML document.\")\n\n        origin = DocumentOrigin(\n            filename=self.file.name or \"file\",\n            mimetype=\"text/html\",\n            binary_hash=self.document_hash,\n        )\n        doc = DoclingDocument(name=self.file.stem or \"file\", origin=origin)\n\n        if cast(HTMLBackendOptions, self.options).render_page:\n            self._render_with_browser()\n            if self._rendered_html:\n                self.soup = BeautifulSoup(self._rendered_html, \"html.parser\")\n\n        if self._rendered_page_images and self._rendered_page_size:\n            render_dpi = cast(HTMLBackendOptions, self.options).render_dpi\n            for page_no, page_image in enumerate(self._rendered_page_images, start=1):\n                doc.add_page(\n                    page_no=page_no,","sourceCodeStart":490,"sourceCodeEnd":526,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/html_backend.py#L490-L526","documentation":"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.","triggerScenarios":"Calling convert() after __init__ failed but the exception was caught upstream; any flow where the BeautifulSoup tree was never created.","commonSituations":"Broad except blocks around backend construction followed by unconditional convert(); orchestration frameworks retrying convert() on the same broken object.","solutions":["Check backend.is_valid() before convert()","Let __init__ exceptions terminate the conversion attempt instead of catching and continuing","Rebuild the backend from the original source for each retry"],"exampleFix":"# before\ndoc = backend.convert()\n\n# after\nif not backend.is_valid():\n    raise ValueError('HTML backend not initialized; check input and init errors')\ndoc = backend.convert()","handlingStrategy":"validation","validationCode":"if not backend.is_valid():\n    raise ValueError('HTML backend not initialized; check init errors first')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Gate convert() behind is_valid()","Do not swallow DocumentLoadError from __init__ and keep going"],"tags":["html","state-machine","lifecycle"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}