BerriAI/litellm · error · ValueError

Missing Azure Document Intelligence Endpoint - Set AZURE_DOC

Error message

Missing Azure Document Intelligence Endpoint - Set AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT environment variable or pass api_base parameter

What it means

Raised during header validation for Azure Document Intelligence OCR when no endpoint is configured: api_base was not passed and the AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT environment variable is unset. The DI client needs a resource-specific endpoint (e.g. https://your-resource.cognitiveservices.azure.com) to build the analyze URL, so the call fails before any network activity. Note this is the header-building path; the same check exists independently in get_complete_url.

Source

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

        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,
        }

        return headers

    def get_complete_url(
        self,
        api_base: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict | None = None,
        **kwargs,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT to your resource endpoint (find it in the Azure portal under your Document Intelligence resource > Keys and Endpoint).
Or pass api_base='https://<resource>.cognitiveservices.azure.com' on the call.
Verify with a preflight check of os.environ in the deployment environment.

Example fix

# before
resp = litellm.aocr_document(model="azure_ai/doc-intelligence/prebuilt-read", document=doc, api_key=key)
# no endpoint anywhere -> ValueError

# after
resp = litellm.aocr_document(
    model="azure_ai/doc-intelligence/prebuilt-read",
    document=doc,
    api_key=key,
    api_base="https://myres.cognitiveservices.azure.com",
)

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv("AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT") and not passed_api_base:
    raise ConfigError("AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT not set")

Try / catch

try:
    resp = litellm.aocr_document(model=m, document=doc)
except ValueError as e:
    if "Missing Azure Document Intelligence Endpoint" in str(e):
        raise ConfigError("configure AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT") from e
    raise

Prevention

Preflight both DI env vars (key AND endpoint) at process start.
Store them together in one secret/config source so they're never half-configured.

When it happens

Trigger: Calling azure_ai doc-intelligence OCR with AZURE_DOCUMENT_INTELLIGENCE_API_KEY set (or api_key passed) but AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT unset and no api_base parameter supplied.

Common situations: Env var configured only on a dev machine and missing in CI/containers; typo in the variable name; assuming the key alone suffices; endpoint stored under a differently named variable (AZURE_AI_API_BASE does not apply to DI).

Related errors

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