docling-project/docling · error · TypeError

path_or_stream must be Path or BytesIO

Error message

path_or_stream must be Path or BytesIO

What it means

The XBRL backend only handles pathlib.Path (file to copy into its temp workspace) or io.BytesIO (bytes to write as instance.xml) as path_or_stream; any other object — str path, open file handle, other stream types — hits the else branch and raises TypeError with this message.

Source

Thrown at docling/backend/xml/xbrl_backend.py:148

                    )
                    zip_paths = [
                        str(item)
                        for item in taxonomy_path.iterdir()
                        if item.is_file()
                        and item.suffix.lower() == ".zip"
                        and zipfile.is_zipfile(item)
                    ]
                    if zip_paths:
                        _log.debug(
                            f"Files to be passed as taxonomy packages: {zip_paths}"
                        )
                if isinstance(path_or_stream, BytesIO):
                    instance_path: Path = tmp_path / "instance.xml"
                    instance_path.write_bytes(path_or_stream.getvalue())
                elif isinstance(path_or_stream, Path):
                    instance_path = Path(shutil.copy2(path_or_stream, tmp_path))
                else:
                    raise TypeError("path_or_stream must be Path or BytesIO")

                # cntlr = Cntlr.Cntlr(logFileName="logToPrint")
                cntlr = Cntlr.Cntlr()
                # Disable remote access for security purposes, unless explicitly set
                if not self.options.enable_remote_fetch:
                    cntlr.webCache.workOffline = True
                    cntlr.modelManager.validateDisclosureSystem = False
                else:
                    # TODO: parametrize the timeout?
                    cntlr.webCache.timeout = _WEB_CACHE_TIMEOUT
                    # TODO: custom set cntlr.webCache.cacheDir?
                    _log.debug(
                        f"Web Cache for remote taxonomy is: {cntlr.webCache.cacheDir}"
                    )

                model = cntlr.modelManager.load(
                    str(instance_path), taxonomyPackages=zip_paths
                )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Wrap strings: pass Path(source) instead of source.
2. For streams, pass BytesIO(raw_bytes); read and encode text content first.
3. Type-check your source before calling: isinstance(src, (Path, BytesIO)).
4. Use DocumentConverter.convert(), which normalizes accepted source types.

Example fix

# before
result = converter.convert("report.xbrl")  # str reaches backend -> TypeError

# after
from pathlib import Path
result = converter.convert(Path("report.xbrl"))

from pathlib import Path
from io import BytesIO

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

from pathlib import Path
from io import BytesIO
from typing import TypeGuard, Union

def is_backend_source(src: object) -> TypeGuard[Union[Path, BytesIO]]:
    return isinstance(src, (Path, BytesIO))

try:
    backend = XBRLBackend(in_doc, src, opts)
except TypeError as e:
    if "Path or BytesIO" in str(e):
        src = Path(src) if isinstance(src, str) else BytesIO(src.read())
        backend = XBRLBackend(in_doc, src, opts)
    else:
        raise

When it happens

Trigger: Constructing XBRLBackend (or converting XBRL via a custom pipeline) with a str filename, an io.TextIOWrapper, or any stream class other than BytesIO as the source.

Common situations: Passing "report.xbrl" as a string; forwarding an already-open file from caller code; wrappers that expose SpooledTemporaryFile or request bodies.

Related errors

• Unexpected: {type(self.path_or_stream)=}
• Unexpected: {type(self.path_or_stream)=}
• Invalid document with hash {self.document_hash}
• ThreadedDoclingParseDocumentBackend only supports iter_pages
• Unsupported input type: {type(self.path_or_stream)}

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