BerriAI/litellm · error · ValueError

Azure Document Intelligence analysis failed: {error_msg}

Error message

Azure Document Intelligence analysis failed: {error_msg}

What it means

Raised during operation polling when Azure DI reports status 'failed'; the error message from Azure's response body (result['error']['message'], or 'Unknown error' if absent) is wrapped into a ValueError. This is an upstream analysis failure — the request itself was accepted, but Document Intelligence could not process the document.

Source

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

            response: HTTP response from operation endpoint

        Returns:
            Operation status string

        Raises:
            ValueError: If operation failed or status is unknown
        """
        try:
            result: Final = response.json()
            status: Final = result.get("status")

            verbose_logger.debug("Azure DI operation status: %s", status)

            if status == "succeeded":
                return "succeeded"
            elif status == "failed":
                error_msg: Final = result.get("error", {}).get("message", "Unknown error")
                raise ValueError(f"Azure Document Intelligence analysis failed: {error_msg}")
            elif status in ["running", "notStarted"]:
                return "running"
            else:
                raise ValueError(f"Unknown operation status: {status}")

        except Exception as e:
            if "succeeded" in str(e) or "failed" in str(e):
                raise
            # If we can't parse JSON, something went wrong
            raise ValueError(f"Failed to parse Azure DI operation response: {e}")

    def _poll_operation_sync(
        self,
        operation_url: str,
        headers: dict[str, str],
        timeout_secs: int,
    ) -> httpx.Response:
        """

View on GitHub (pinned to 6c2dcb801b)

Solutions

Read the wrapped error message — it is Azure's own failure reason; address that cause (repair file, remove password, convert format).
Pre-validate uploads client-side: check MIME type, size, page count against Azure DI limits before submitting.
Isolate per-document failures with try/except so one bad file doesn't kill a batch; optionally retry once for transient Azure failures.

Example fix

# before
results = [litellm.aocr_document(model=m, document=d) for d in docs]  # one bad file aborts batch

# after
results = []
for d in docs:
    try:
        results.append(litellm.aocr_document(model=m, document=d))
    except ValueError as e:
        if "analysis failed" in str(e):
            results.append({"doc": d["document_url"], "error": str(e)})  # quarantine bad file
        else:
            raise

Defensive patterns

Strategy: try-catch

Try / catch

try:
    resp = litellm.aocr_document(model=m, document=doc)
except ValueError as e:
    if "analysis failed" in str(e):
        mark_document_unprocessable(doc, reason=str(e))  # quarantine, continue batch
    else:
        raise

Prevention

Pre-validate PDFs: not encrypted, valid structure, within page/size limits.
Quarantine failed documents instead of aborting the whole batch.

When it happens

Trigger: Polling an analyze operation whose JSON status is 'failed': corrupted or password-protected PDFs, unsupported formats, unreadable scans, documents exceeding Azure limits, or an Azure-side service failure. The inner error_msg carries Azure's specific reason.

Common situations: Processing user-uploaded files at scale (some corrupt/protected); scanned images too low quality; files over the page/size limits; free-tier throttling surfacing as failed operations.

Related errors

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