BerriAI/litellm · error · ValueError

Invalid Azure Blob Storage URL: {storage_url}

Error message

Invalid Azure Blob Storage URL: {storage_url}

What it means

Raised by AzureBlobStorageBackend when downloading a file whose URL hostname does not contain '.blob.'. The backend parses the storage URL with urlparse and expects the Azure Blob Storage shape https://{account}.blob.{endpoint_suffix}/{container}/{path}; anything else (Gen2 dfs. endpoints, SAS URLs to other services, plain https URLs) is rejected.

Source

Thrown at litellm/llms/base_llm/files/azure_blob_storage_backend.py:237

        )
        response.raise_for_status()

    async def download_file(self, storage_url: str) -> bytes:
        """
        Download a file from Azure Blob Storage.

        Args:
            storage_url: Blob URL in format: https://{account}.blob.{endpoint_suffix}/{container}/{path}

        Returns:
            bytes: File content
        """
        try:
            # Parse blob URL to extract path
            # URL format: https://{account}.blob.{endpoint_suffix}/{container}/{path}
            parsed_url: Final = urlparse(storage_url)
            if ".blob." not in (parsed_url.hostname or ""):
                raise ValueError(f"Invalid Azure Blob Storage URL: {storage_url}")

            # Extract path after container name
            _, _, file_path = parsed_url.path.lstrip("/").partition("/")
            if not file_path:
                raise ValueError(f"Invalid Azure Blob Storage URL format: {storage_url}")

            if self.azure_storage_account_key:
                # Use Azure SDK (reuse logger's service client)
                return await self._download_file_with_account_key(file_path)
            else:
                # Use REST API (reuse logger's token management)
                return await self._download_file_with_azure_ad(file_path)

        except Exception as e:
            verbose_logger.exception("Error downloading file from Azure Blob Storage: %s", e)
            raise

    async def _download_file_with_account_key(self, file_path: str) -> bytes:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Use the blob endpoint form: https://{account}.blob.core.windows.net/{container}/{path}.
2. If you intended ADLS Gen2, this backend does not support dfs. URLs — create/use a blob endpoint for the same storage account.
3. Verify AZURE_STORAGE_BUCKET_URL / the stored file_url value is the full blob URL, including container and path.
4. For custom domains, map them back to the account.blob.core.windows.net form before passing to litellm.

Example fix

# before
file_url = 'https://mystorage.dfs.core.windows.net/files/report.pdf'  # ValueError

# after
file_url = 'https://mystorage.blob.core.windows.net/files/report.pdf'

from urllib.parse import urlparse

def is_valid_blob_url(url: str) -> bool:
    host = urlparse(url).hostname or ''
    return host.endswith('.blob.core.windows.net') or '.blob.' in host

When it happens

Trigger: Configuring litellm_proxy / enterprise file management with AZURE_STORAGE_BUCKET_URL or a file_url pointing to an endpoint like 'https://acct.dfs.core.windows.net/...' (ADLS Gen2) or a non-Azure URL, then triggering a file download; the hostname check ".blob." not in hostname fires.

Common situations: Mixing up Azure Data Lake Gen2 (dfs.) and Blob (blob.) endpoints; copying the wrong connection string's endpoint; using a CDN or custom domain in front of the storage account; trailing config mistakes in AZURE_STORAGE_* env vars.

Related errors

• Invalid Azure Blob Storage URL format: {storage_url}
• 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/7d0df89fd9cc6a00. Report an issue: GitHub.