BerriAI/litellm · error · ValueError

document must be a dict with 'type' and URL/file field, got

Error message

document must be a dict with 'type' and URL/file field, got {type(document)}

What it means

Type guard at the top of _prepare_ocr_request: the document argument is not a dict (Mapping alone is not enough downstream), so its 'type' and URL/file payload cannot be read. The received type is echoed in the message.

Source

Thrown at litellm/ocr/main.py:79

    "vertex_ai",
}


def _prepare_ocr_request(
    model: str,
    document: Mapping[str, object],
    api_key: str | None,
    api_base: str | None,
    timeout: float | httpx.Timeout | None,
    custom_llm_provider: str | None,
    extra_headers: dict[str, object] | None,
    kwargs: dict[str, object],
) -> _PreparedOCRRequest:
    litellm_logging_obj: Final = cast(LiteLLMLoggingObj, kwargs.pop("litellm_logging_obj"))
    litellm_call_id: Final = cast(str | None, kwargs.get("litellm_call_id", None))

    if not isinstance(document, dict):
        raise ValueError(f"document must be a dict with 'type' and URL/file field, got {type(document)}")

    doc_type = document.get("type")

    if doc_type == "file":
        document = convert_file_document_to_url_document(document)
        doc_type = document.get("type")

    if doc_type not in ["document_url", "image_url"]:
        raise ValueError(f"Invalid document type: {doc_type}. Must be 'document_url', 'image_url', or 'file'")

    caller_supplied_api_base: Final = api_base is not None

    (
        model,
        custom_llm_provider,
        dynamic_api_key,
        dynamic_api_base,
    ) = litellm.get_llm_provider(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass the document as a dict with 'type' plus the corresponding URL or file field, e.g. {'type': 'image_url', 'image_url': {...}}.
2. Convert other document representations into this dict structure before calling the OCR API.

When it happens

Trigger: Thrown at litellm/ocr/main.py:79 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/00d50d4b6d72b556. Report an issue: GitHub.