BerriAI/litellm · error · ValueError

document with type='file' must include a 'file' field contai

Error message

document with type='file' must include a 'file' field containing a pathlib.Path, file-like object, or bytes

What it means

Validation in the file-type OCR document converter: the 'file' value is not a pathlib.Path, file-like object, or bytes (the shapes that can be safely base64-inlined), so it cannot be converted to a document_url data URI.

Source

Thrown at litellm/ocr/main.py:496

    """
    Convert a file-type document dict to a document_url-type document dict
    with an inline base64 data URI.

    Accepts document dicts like:
        {"type": "file", "file": Path("/path/to/doc.pdf")}       # pathlib.Path
        {"type": "file", "file": <binary file-like object>}      # file-like object (BinaryIO)
        {"type": "file", "file": b"raw bytes"}                   # raw bytes

    Bare ``str`` paths are not accepted — pass a ``pathlib.Path`` or
    ``open(path, "rb")`` instead. See the str check below for the rationale.

    Returns:
        {"type": "document_url", "document_url": "data:<mime>;base64,<data>"}
        or {"type": "image_url", "image_url": "data:<mime>;base64,<data>"}
    """
    file_input: Final = document.get("file")
    if file_input is None:
        raise ValueError(
            "document with type='file' must include a 'file' field containing "
            "a pathlib.Path, file-like object, or bytes"
        )

    file_bytes: bytes
    mime_type: str = "application/octet-stream"
    file_name: str | None = None

    if isinstance(file_input, str):
        # Bare strings are rejected here. The OCR ``document`` accepts a
        # ``{"type": "file", "file": <value>}`` shape, and when this helper
        # runs in a proxy request handler ``<value>`` is attacker-controlled.
        # Opening it as a path is an arbitrary local file read on the proxy
        # host, which is then base64-encoded and forwarded to the OCR
        # provider — an exfiltration primitive.
        raise ValueError(
            "OCR file input does not accept bare str values. Pass bytes, "
            "a pathlib.Path, or a file-like object. To OCR a local file "

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass the file via the 'file' field of the document object: {'type':'file','file': <pathlib.Path|file-like|bytes>}.

Example fix

documents=[{'type':'file','file': open('scan.pdf','rb')}]

When it happens

Trigger: Thrown at litellm/ocr/main.py:496 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/e71b86878ab792ec. Report an issue: GitHub.