BerriAI/litellm · error · ValueError

Azure AI API key is required. Please set 'AZURE_AI_API_KEY'

Error message

Azure AI API key is required. Please set 'AZURE_AI_API_KEY' or 'litellm.azure_key'

What it means

The Azure AI rerank auth header is a Bearer token built from an API key. validate_environment checks the api_key parameter, then AZURE_AI_API_KEY, then the global litellm.azure_key; if all are None it cannot construct the Authorization header and raises. Unlike Azure OpenAI, no AzureEntraID/managed-identity fallback applies here.

Source

Thrown at litellm/llms/azure_ai/rerank/transformation.py:72

                api_base=str(original_url.copy_with(path=normalized_path or "/")),
                ending_path="/rerank",
            )

        # Backwards compatible default: Azure AI rerank was originally exposed under /v1/rerank
        return _add_path_to_api_base(api_base=api_base, ending_path="/v1/rerank")

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        optional_params: dict | None = None,
    ) -> dict:
        if api_key is None:
            api_key = get_secret_str("AZURE_AI_API_KEY") or litellm.azure_key

        if api_key is None:
            raise ValueError("Azure AI API key is required. Please set 'AZURE_AI_API_KEY' or 'litellm.azure_key'")

        default_headers: Final = {
            "Authorization": f"Bearer {api_key}",
            "accept": "application/json",
            "content-type": "application/json",
        }

        # If 'Authorization' is provided in headers, it overrides the default.
        if "Authorization" in headers:
            default_headers["Authorization"] = headers["Authorization"]

        # Merge other headers, overriding any default ones except Authorization
        return {**default_headers, **headers}

    def transform_rerank_response(
        self,
        model: str,
        raw_response: httpx.Response,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. export AZURE_AI_API_KEY=<your-key> (note: AZURE_AI_API_KEY, not AZURE_API_KEY)
2. Or pass api_key directly to litellm.rerank(...)
3. Or set the global: litellm.azure_key = '<your-key>'

Example fix

# before
os.environ['AZURE_API_KEY'] = key  # wrong variable
litellm.rerank(model='azure_ai/cohere-rerank-v3.5', query=q, documents=docs, api_base=base)

# after
os.environ['AZURE_AI_API_KEY'] = key
litellm.rerank(model='azure_ai/cohere-rerank-v3.5', query=q, documents=docs, api_base=base)

api_key = os.environ.get('AZURE_AI_API_KEY')
assert api_key, 'Set AZURE_AI_API_KEY (not AZURE_API_KEY) for azure_ai rerank'

When it happens

Trigger: litellm.rerank(model='azure_ai/...', ...) with no api_key argument while AZURE_AI_API_KEY is unset and litellm.azure_key was never assigned. Setting only AZURE_API_KEY (the Azure OpenAI var) does not satisfy this check.

Common situations: Reusing Azure OpenAI env var names (AZURE_API_KEY) for Azure AI resource calls; rotating keys and clearing the env var; proxy model entry with api_key omitted.

Related errors

• Azure AI API Base is required. api_base=None. Set in call or
• api_key is required for Azure AI Speech transcription.
• AZURE_CLIENT_ID and AZURE_TENANT_ID must be set
• OIDC token could not be retrieved from secret manager.
• {req_token.text}

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