{"record":{"id":"a8524fbf610b4c9c","repo":"docling-project/docling","slug":"unexpected-type-self-path-or-stream-a8524f","errorCode":null,"errorMessage":"Unexpected: {type(self.path_or_stream)=}","messagePattern":"Unexpected: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/backend/xml/doclang_archive_backend.py","lineNumber":54,"sourceCode":"    @override\n    def supported_formats(cls) -> set[InputFormat]:\n        return {InputFormat.DCLX}\n\n    def _get_doc_or_err(self) -> Union[DoclingDocument, Exception]:\n        try:\n            if isinstance(self.path_or_stream, Path):\n                doc = DoclingDocument.load_from_doclang_archive(self.path_or_stream)\n            elif isinstance(self.path_or_stream, BytesIO):\n                self._temp_dir = Path(tempfile.mkdtemp(prefix=\"docling_dclx_\"))\n                archive_path = self._temp_dir / (self.file.name or \"document.dclx\")\n                archive_path.write_bytes(self.path_or_stream.getvalue())\n                artifacts_dir = self._temp_dir / \"artifacts\"\n                doc = DoclingDocument.load_from_doclang_archive(\n                    archive_path,\n                    artifacts_dir=artifacts_dir,\n                )\n            else:\n                raise RuntimeError(f\"Unexpected: {type(self.path_or_stream)=}\")\n\n            doc.origin = DocumentOrigin(\n                filename=self.file.name or \"file\",\n                mimetype=_DCLX_MIMETYPE,\n                binary_hash=self.document_hash,\n            )\n            return doc\n        except Exception as e:\n            return e\n\n    @override\n    def convert(self) -> DoclingDocument:\n        if isinstance(self._doc_or_err, DoclingDocument):\n            return self._doc_or_err\n\n        raise self._doc_or_err\n\n    @override","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/xml/doclang_archive_backend.py#L36-L72","documentation":"DoclangArchiveBackend's internal loader only accepts a pathlib.Path or io.BytesIO as path_or_stream; any other type (str path, open file object, temp file handle) hits the else-branch RuntimeError. The error is captured by _get_doc_or_err and later surfaced as the conversion error, so the f-string type detail is preserved in the message.","triggerScenarios":"Constructing DoclangArchiveBackend (or converting a .dclx doclang archive) with path_or_stream of an unexpected type — most commonly a plain string filename instead of Path, or a raw file object opened by caller code.","commonSituations":"Custom pipelines that pass str paths for convenience; adapters that forward an already-open file; code migrated from an API that accepted strings.","solutions":["Wrap the value: pass Path(my_string) instead of the string.","Read the bytes yourself and pass BytesIO(data) for in-memory handling.","Type-check before constructing the backend (isinstance against (Path, BytesIO)).","Prefer DocumentConverter.convert(source), which normalizes accepted sources for you."],"exampleFix":"# before\nbackend = DoclangArchiveBackend(in_doc, \"/data/report.dclx\")  # str -> RuntimeError\n\n# after\nfrom pathlib import Path\nbackend = DoclangArchiveBackend(in_doc, Path(\"/data/report.dclx\"))","handlingStrategy":"type-guard","validationCode":"from pathlib import Path\nfrom io import BytesIO\n\ndef acceptable_source(src) -> bool:\n    return isinstance(src, (Path, BytesIO))","typeGuard":"from pathlib import Path\nfrom io import BytesIO\nfrom typing import Union\n\ndef is_backend_source(src: object) -> TypeGuard[Union[Path, BytesIO]]:\n    return isinstance(src, (Path, BytesIO))","tryCatchPattern":"try:\n    doc = backend.convert()\nexcept Exception as e:\n    if \"Unexpected: type(self.path_or_stream)\" in str(e):\n        raise TypeError(\"pass Path or BytesIO to doclang archive backend\") from e\n    raise","preventionTips":["Standardize on Path for files and BytesIO for buffers at your pipeline boundary.","Prefer DocumentConverter.convert() which normalizes source types."],"tags":["doclang","type-error","api-misuse","backends"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}