{"record":{"id":"5a38feed26263ca9","repo":"docling-project/docling","slug":"could-not-initialize-html-backend-for-file-with-ha","errorCode":null,"errorMessage":"Could not initialize HTML backend for file with hash {self.document_hash}.","messagePattern":"Could not initialize HTML backend for file with hash (.+?)\\.","errorType":"exception","errorClass":"DocumentLoadError","httpStatus":null,"severity":"error","filePath":"docling/backend/html_backend.py","lineNumber":479,"sourceCode":"        self._rendered_page_images: list[Image.Image] = []\n        self._rendered_page_size: Optional[Size] = None\n        self._suppressed_tag_ids_stack: list[set[str]] = []\n        self._suppressed_tag_obj_ids_stack: list[set[int]] = []\n        self._form_fields_by_key_id_stack: list[dict[str, _ExtractedFormField]] = []\n        self._tag_name_by_docling_id_cache: dict[str, str] = {}\n        self._generated_html_id_counter: int = 0\n        self._render_visibility_cache: dict[int, bool] = {}\n\n        try:\n            raw = (\n                path_or_stream.getvalue()\n                if isinstance(path_or_stream, BytesIO)\n                else Path(path_or_stream).read_bytes()\n            )\n            self._raw_html_bytes = raw\n            self.soup = BeautifulSoup(raw, \"html.parser\")\n        except Exception as e:\n            raise DocumentLoadError(\n                \"Could not initialize HTML backend for file with \"\n                f\"hash {self.document_hash}.\"\n            ) from e\n\n    @override\n    def is_valid(self) -> bool:\n        return self.soup is not None\n\n    @classmethod\n    @override\n    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","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/html_backend.py#L461-L497","documentation":"HTMLDocumentBackend.__init__ wraps exceptions from reading the raw bytes and building the BeautifulSoup tree into DocumentLoadError. Because html.parser is extremely tolerant, the read step (OSError on a bad path, stream already consumed) is the most common cause; genuine parser errors also land here. The original exception is preserved as __cause__.","triggerScenarios":"Path that does not exist or lacks read permission; a BytesIO already drained by earlier code; rare tokenizer explosions on pathological inputs.","commonSituations":"Reusing a stream across two conversions; TOCTOU file deletion; chroot/container without read access to mounted HTML files.","solutions":["Inspect exc.__cause__ to distinguish I/O errors from parser errors","Verify Path.exists()/readable() or reset streams with seek(0) before conversion","Read the bytes once yourself and pass a fresh BytesIO"],"exampleFix":"# before\nres = converter.convert(html_path)\n\n# after\nraw = html_path.read_bytes()  # surfaces I/O problems directly\nres = converter.convert(BytesIO(raw))","handlingStrategy":"try-catch","validationCode":"src = Path(html_path)\nassert src.is_file() and src.stat().st_size > 0, f'HTML source unreadable: {src}'\nraw = src.read_bytes()  # surface I/O errors before the backend wraps them","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(BytesIO(raw))\nexcept DocumentLoadError as exc:\n    log.warning('HTML init failed: %s', exc.__cause__ or exc)\n    raise","preventionTips":["Read bytes once and pass a fresh BytesIO per attempt","seek(0) any reused stream before conversion"],"tags":["html","file-io","stream-state","parsing"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}