{"record":{"id":"955439e66e2f86bd","repo":"docling-project/docling","slug":"the-beautifulsoup4-package-is-required-to-proces","errorCode":null,"errorMessage":"The 'beautifulsoup4' package is required to process HTML files. Install it with `pip install 'docling-slim[format-html]'`.","messagePattern":"The 'beautifulsoup4' package is required to process HTML files\\. Install it with `pip install 'docling-slim\\[format-html\\]'`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/backend/html_backend.py","lineNumber":428,"sourceCode":"                # Create new paragraph after each segment except the last\n                if i < len(sub_texts) - 1:\n                    super_list.append(active_annotated_text_list)\n                    active_annotated_text_list = AnnotatedTextList()\n        if active_annotated_text_list:\n            super_list.append(active_annotated_text_list)\n        return super_list\n\n\nclass HTMLDocumentBackend(DeclarativeDocumentBackend):\n    @override\n    def __init__(\n        self,\n        in_doc: InputDocument,\n        path_or_stream: Union[BytesIO, Path],\n        options: Optional[HTMLBackendOptions] = None,\n    ):\n        if not _BS4_AVAILABLE:\n            raise ImportError(_INSTALL_HINT) from _BS4_IMPORT_ERROR\n        if options is None:\n            options = HTMLBackendOptions()\n        super().__init__(in_doc, path_or_stream, options)\n        self.options: HTMLBackendOptions\n        self.soup: Optional[BeautifulSoup] = None\n        self.path_or_stream: Union[BytesIO, Path] = path_or_stream\n        self.base_path: Optional[str] = (\n            str(options.source_uri) if options.source_uri is not None else None\n        )\n        self._image_loader = ImageResourceLoader(\n            enable_local_fetch=options.enable_local_fetch,\n            enable_remote_fetch=options.enable_remote_fetch,\n            max_image_data_base64_bytes=options.max_image_data_base64_bytes,\n            max_remote_image_bytes=options.max_remote_image_bytes,\n            max_redirects=options.max_redirects,\n            headers=options.headers,\n        )\n","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/html_backend.py#L410-L446","documentation":"HTMLDocumentBackend.__init__ raises ImportError before super().__init__() when beautifulsoup4 (bs4) is unavailable, chaining the original import error. HTML parsing is an optional extra in docling-slim, so this is the documented, actionable signal that the extra is missing.","triggerScenarios":"Converting HTML (or any pipeline that instantiates HTMLDocumentBackend, e.g. EPUB content files) in an environment lacking bs4 — typically docling-slim installed without format-html.","commonSituations":"Slim Docker images; dependency-stripped Lambda layers; installing docling-slim explicitly for size and forgetting which formats are needed.","solutions":["Install the extra: pip install 'docling-slim[format-html]'","Or install full docling which bundles format extras","Record required format extras in the deployment manifest"],"exampleFix":"# before\npip install docling-slim\n\n# after\npip install 'docling-slim[format-html]'","handlingStrategy":"validation","validationCode":"try:\n    import bs4  # noqa: F401\nexcept ImportError:\n    raise RuntimeError(\"Install: pip install 'docling-slim[format-html]'\")","typeGuard":null,"tryCatchPattern":"try:\n    result = converter.convert(src)\nexcept ImportError as exc:\n    if 'beautifulsoup4' in str(exc):\n        install_or_skip('docling-slim[format-html]')\n    raise","preventionTips":["Declare every format extra you use in deployment manifests","Probe optional imports at service startup"],"tags":["html","optional-dependency","installation","importerror"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}