BerriAI/litellm · error · ValueError

Document URL is required

Error message

Document URL is required

What it means

Raised when the document dict has a valid type but the corresponding URL field is empty/missing — e.g. type 'document_url' with no 'document_url' value, or an empty string. Azure DI needs either a reachable URL or a base64 data URI to analyze, so the request cannot be built and fails client-side.

Source

Thrown at litellm/llms/azure_ai/ocr/document_intelligence/transformation.py:373

        """
        verbose_logger.debug("Azure Document Intelligence transform_ocr_request - model: %s", model)

        if not isinstance(document, dict):
            raise ValueError(f"Expected document dict, got {type(document)}")

        # Extract document URL from Mistral format
        doc_type: Final = document.get("type")
        document_url = None

        if doc_type == "document_url":
            document_url = document.get("document_url", "")
        elif doc_type == "image_url":
            document_url = document.get("image_url", "")
        else:
            raise ValueError(f"Invalid document type: {doc_type}. Must be 'document_url' or 'image_url'")

        if not document_url:
            raise ValueError("Document URL is required")

        # Build Azure DI request
        data: Final[dict[str, Any]] = {}

        # Check if it's a data URI (base64)
        if document_url.startswith("data:"):
            # Extract base64 content
            base64_content: Final = self._extract_base64_from_data_uri(document_url)
            data["base64Source"] = base64_content
            verbose_logger.debug("Using base64Source for Azure Document Intelligence")
        else:
            # Regular URL
            data["urlSource"] = document_url
            verbose_logger.debug("Using urlSource for Azure Document Intelligence")

        # Azure DI: `pages` is a query param (wired in get_complete_url),
        # not a body field. Other Mistral-specific params (e.g.
        # include_image_base64, image_limit) are unsupported and ignored.

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Supply a non-empty http(s) URL under the key matching the type, or a data URI like 'data:application/pdf;base64,...'.
2. Check for empty/missing URL before calling and return a user-facing validation error.
3. If uploading to blob storage first, verify the upload succeeded and the SAS URL was actually returned.

Example fix

# before
doc = {"type": "document_url", "document_url": upload_result.get("url", "")}  # empty on failure

# after
url = upload_result.get("url")
if not url:
    raise ValueError("upload failed; no document URL")
doc = {"type": "document_url", "document_url": url}

def document_with_url(doc: dict) -> bool:
    return bool(doc.get(doc.get("type", ""), ""))  # URL key must match type and be non-empty

When it happens

Trigger: Calling azure_ai doc-intelligence OCR with {'type': 'document_url', 'document_url': ''}, a dict missing the URL key (document.get returns ''), or a falsy value like None under the URL key.

Common situations: Building the dict from optional form fields that were left blank; key-name mismatch ('url' instead of 'document_url'); earlier processing step returned an empty string for the upload URL.

Related errors

• Expected document dict, got {type(document)}
• Invalid document type: {doc_type}. Must be 'document_url' or
• Invalid `pages` string for Azure Document Intelligence: {pag
• `pages` integers must be >= 0 (Mistral 0-based indices)
• Invalid `pages` list for Azure Document Intelligence: {pages

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/fd52a95fc0ca90e8. Report an issue: GitHub.