BerriAI/litellm · error · ValueError

Invalid Azure Blob Storage URL format: {storage_url}

Error message

Invalid Azure Blob Storage URL format: {storage_url}

What it means

Raised by AzureBlobStorageBackend after URL parsing succeeds but path extraction yields nothing: parsed_url.path stripped of '/' and partitioned on '/' leaves an empty file_path. This means the URL only had the container (e.g. .../container or .../container/) and no blob path, so there is no file to download.

Source

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

        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:
        """Download file using Azure SDK with account key."""
        # Reuse the logger's service client method
        service_client: Final = await self.get_service_client()
        file_system_client: Final = service_client.get_file_system_client(file_system=self.azure_storage_file_system)
        # Ensure filesystem exists (should already exist, but check for safety)

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Include the full blob path after the container: https://{acct}.blob.core.windows.net/{container}/{blob/path.pdf}.
2. Check the code that generates/stores file_url for off-by-one or empty-filename bugs.
3. If listing files in a container was the intent, use the Azure SDK listing API instead of this download path.
4. URL-encode blob names containing spaces/special chars so the path segment is not lost.

Example fix

# before
storage_url = 'https://acct.blob.core.windows.net/uploads/'  # no blob path -> ValueError

# after
storage_url = 'https://acct.blob.core.windows.net/uploads/invoice-42.pdf'

from urllib.parse import urlparse

def has_blob_path(url: str) -> bool:
    path = urlparse(url).path.lstrip('/')
    _, _, file_path = path.partition('/')
    return bool(file_path)

When it happens

Trigger: Passing a container-root URL like 'https://acct.blob.core.windows.net/container' or '.../container/' to the file download API; a stored file_url truncated during DB insert; blob names that were empty or stripped of slashes.

Common situations: Building download URLs by concatenating container + optional filename where filename is empty; frontend sending just the folder prefix; copy-paste of a container SAS URL instead of a blob URL.

Related errors

• Invalid Azure Blob Storage URL: {storage_url}
• Filesystem {self.azure_storage_file_system} does not exist
• 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

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