BerriAI/litellm · error · ValueError

Azure AI API Base must be an absolute URL including scheme (

Error message

Azure AI API Base must be an absolute URL including scheme (e.g. 'https://<resource>.services.ai.azure.com'). Got api_base={api_base!r}.

What it means

After confirming api_base exists, the rerank config parses it with httpx.URL and requires it to be absolute (include a scheme like https://). A bare host such as my-resource.services.ai.azure.com has no scheme, so is_absolute_url is false and the URL cannot be safely joined with the rerank path.

Source

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

class AzureAIRerankConfig(CohereRerankConfig):
    """
    Azure AI Rerank - Follows the same Spec as Cohere Rerank
    """

    def get_complete_url(
        self,
        api_base: str | None,
        model: str,
        optional_params: dict | None = None,
    ) -> str:
        if api_base is None:
            raise ValueError(
                "Azure AI API Base is required. api_base=None. Set in call or via `AZURE_AI_API_BASE` env var."
            )
        original_url: Final = httpx.URL(api_base)
        if not original_url.is_absolute_url:
            raise ValueError(
                "Azure AI API Base must be an absolute URL including scheme (e.g. "
                "'https://<resource>.services.ai.azure.com'). "
                f"Got api_base={api_base!r}."
            )
        normalized_path: Final = original_url.path.rstrip("/")

        # Allow callers to pass either full v1/v2 rerank endpoints:
        # - https://<resource>.services.ai.azure.com/v1/rerank
        # - https://<resource>.services.ai.azure.com/providers/cohere/v2/rerank
        if normalized_path.endswith("/v1/rerank") or normalized_path.endswith("/v2/rerank"):
            return str(original_url.copy_with(path=normalized_path or "/"))

        # If callers pass just the version path (e.g. ".../v2" or ".../providers/cohere/v2"), append "/rerank"
        if (
            normalized_path.endswith("/v1")
            or normalized_path.endswith("/v2")
            or normalized_path.endswith("/providers/cohere/v2")
        ):

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Include the scheme: api_base='https://<resource>.services.ai.azure.com'
2. Add a normalization step in your code: api_base = api_base if api_base.startswith('http') else 'https://' + api_base
3. Check the exact value being sent: log repr(api_base) before the call

Example fix

# before
litellm.rerank(model='azure_ai/cohere-rerank-v3.5', query=q, documents=docs, api_base='my-resource.services.ai.azure.com')

# after
litellm.rerank(model='azure_ai/cohere-rerank-v3.5', query=q, documents=docs, api_base='https://my-resource.services.ai.azure.com')

from urllib.parse import urlparse

def normalize_api_base(base: str) -> str:
    if not urlparse(base).scheme:
        base = 'https://' + base
    return base.rstrip('/')

def is_absolute_http_url(value) -> bool:
    try:
        from urllib.parse import urlparse
        p = urlparse(value)
        return p.scheme in ('http', 'https') and bool(p.netloc)
    except Exception:
        return False

When it happens

Trigger: Passing api_base='my-resource.services.ai.azure.com' or 'my-resource.services.ai.azure.com/v1/rerank' (no https:// prefix). Also happens when a trailing config value had the scheme stripped by string manipulation or a templating mistake.

Common situations: Storing endpoints in config without the scheme; environment variables copied from Azure portal 'copy host' buttons that omit https://; constructing api_base by concatenation and dropping the scheme.

Related errors

• Azure AI API Base is required. api_base=None. Set in call or
• AZURE_SENTINEL_DCR_IMMUTABLE_ID is required. Set it as an en
• AZURE_SENTINEL_ENDPOINT is required. Set it as an environmen
• AZURE_SENTINEL_TENANT_ID or AZURE_TENANT_ID is required. Set
• AZURE_SENTINEL_CLIENT_ID or AZURE_CLIENT_ID is required. Set

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