docling-project/docling · error · RuntimeError

Unexpected: {type(self.path_or_stream)=}

Error message

Unexpected: {type(self.path_or_stream)=}

What it means

DoclingJSONBackend._get_doc_or_err() only accepts Path (opened as UTF-8 text) or BytesIO inputs and raises RuntimeError for anything else; because the method captures exceptions and stores them, the RuntimeError is re-raised later from convert() rather than at construction. String paths and generic file objects are not part of the contract.

Source

Thrown at docling/backend/json/docling_json_backend.py:48

    @override
    def supports_pagination(cls) -> bool:
        return False

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

    def _get_doc_or_err(self) -> Union[DoclingDocument, Exception]:
        try:
            json_data: Union[str, bytes]
            if isinstance(self.path_or_stream, Path):
                with open(self.path_or_stream, encoding="utf-8") as f:
                    json_data = f.read()
            elif isinstance(self.path_or_stream, BytesIO):
                json_data = self.path_or_stream.getvalue()
            else:
                raise RuntimeError(f"Unexpected: {type(self.path_or_stream)=}")
            return DoclingDocument.model_validate_json(json_data=json_data)
        except Exception as e:
            return e

    @override
    def convert(self) -> DoclingDocument:
        if isinstance(self._doc_or_err, DoclingDocument):
            return self._doc_or_err
        else:
            raise self._doc_or_err

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Wrap inputs: Path(p) for strings, BytesIO(data) for raw bytes/streams
2. Check the exception at convert() time — init will not fail for a bad type
3. Ensure the payload is UTF-8 encoded JSON of a serialized DoclingDocument

Example fix

# before
backend = DoclingJSONBackend(in_doc, '/data/doc.docling.json')  # str: fails at convert()

# after
from pathlib import Path
backend = DoclingJSONBackend(in_doc, Path('/data/doc.docling.json'))

from io import BytesIO
from pathlib import Path

src = Path('/data/doc.docling.json') if isinstance(src, str) else src
assert isinstance(src, (Path, BytesIO)), f'JSON backend needs Path or BytesIO, got {type(src)!r}'

def is_json_backend_source(src) -> bool:
    return isinstance(src, (Path, BytesIO))

When it happens

Trigger: Passing a str path, an open file object, or io.StringIO as path_or_stream to the JSON backend; the error then surfaces at convert() time, deferred from init.

Common situations: FastAPI/web handlers forwarding uploaded file objects; scripts using os.path strings; the deferred raise confusing developers because construction succeeded.

Related errors

• Unsupported input type: {type(self.path_or_stream)}
• Could not read the EBCDIC layout {self.options.layout_file}.
• Incompatible file format {self.input_format} was passed to I
• Unexpected: {type(self.path_or_stream)=}
• Unexpected: {type(self.path_or_stream)=}

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