BerriAI/litellm · error · ValueError

Missing Azure Document Intelligence API Key - Set AZURE_DOCU

Error message

Missing Azure Document Intelligence API Key - Set AZURE_DOCUMENT_INTELLIGENCE_API_KEY environment variable or pass api_key parameter

What it means

Raised while building request headers for Azure Document Intelligence OCR when no API key is available: neither an explicit api_key parameter nor the AZURE_DOCUMENT_INTELLIGENCE_API_KEY environment variable is set. Azure DI authenticates via the Ocp-Apim-Subscription-Key header, which cannot be constructed without the key, so the call is aborted before any request.

Source

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

        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        api_base: str | None = None,
        litellm_params: dict | None = None,
        **kwargs,
    ) -> dict:
        """
        Validate environment and return headers for Azure Document Intelligence.

        Authentication uses Ocp-Apim-Subscription-Key header.
        """
        # Get API key from environment if not provided
        if api_key is None:
            api_key = get_secret_str(AZURE_DOCUMENT_INTELLIGENCE_API_KEY_ENV_VAR)

        if api_key is None:
            raise ValueError(
                "Missing Azure Document Intelligence API Key - Set AZURE_DOCUMENT_INTELLIGENCE_API_KEY environment variable or pass api_key parameter"
            )

        # Validate API base/endpoint is provided
        if api_base is None:
            api_base = get_secret_str("AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT")

        if api_base is None:
            raise ValueError(
                "Missing Azure Document Intelligence Endpoint - Set AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT environment variable or pass api_base parameter"
            )

        headers = {
            "Ocp-Apim-Subscription-Key": api_key,
            "Content-Type": "application/json",
            **headers,
        }

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set AZURE_DOCUMENT_INTELLIGENCE_API_KEY in the environment of the running process (export it, add to .env/secret manager, or docker env).
Or pass the key explicitly: litellm.oclr(..., api_key='...', api_base='https://<resource>.cognitiveservices.azure.com').
In a server, confirm the variable is present via os.environ before the call, and reload/redeploy after adding it.

Example fix

# before
os.environ["AZURE_AI_API_KEY"] = "..."  # wrong variable for DI
resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-read", document=doc)

# after
os.environ["AZURE_DOCUMENT_INTELLIGENCE_API_KEY"] = "..."
os.environ["AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT"] = "https://myres.cognitiveservices.azure.com"
resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-read", document=doc)

Defensive patterns

Strategy: validation

Validate before calling

import os
assert os.getenv("AZURE_DOCUMENT_INTELLIGENCE_API_KEY") or passed_api_key, "DI key missing"

Try / catch

try:
    resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-read", document=doc)
except ValueError as e:
    if "Missing Azure Document Intelligence API Key" in str(e):
        raise ConfigError("set AZURE_DOCUMENT_INTELLIGENCE_API_KEY") from e
    raise

Prevention

Add a startup preflight check for AZURE_DOCUMENT_INTELLIGENCE_API_KEY in the service env.
Don't reuse AZURE_AI_API_KEY for DI — they are separate credentials.

When it happens

Trigger: Calling litellm OCR with an 'azure_ai/doc-intelligence/...' model while AZURE_DOCUMENT_INTELLIGENCE_API_KEY is unset in the process environment and no api_key is passed in params/litellm_params.

Common situations: Env var set in a shell but not exported (or set after the process started; missing from docker/systemd/serverless env); typo in the variable name; assuming AZURE_AI_API_KEY covers DI (it doesn't — DI needs its own key).

Related errors

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