BerriAI/litellm · error · ValueError

Invalid URL format: {remote_url}. Expected: {storage_type}:/

Error message

Invalid URL format: {remote_url}. Expected: {storage_type}://bucket-name/path/to/module.instance

What it means

The remote URL parsed to a supported scheme but split on '/' produced no path segment after the bucket name (e.g. 's3://my-bucket'), so there is no module path and instance name to load. The URL must contain bucket plus a dotted module.instance path.

Source

Thrown at litellm/proxy/types_utils/utils.py:99

        Any: The loaded instance
    """
    try:
        from litellm._logging import verbose_proxy_logger

        # Parse the URL
        if remote_url.startswith("s3://"):
            storage_type = "s3"
            url_without_prefix = remote_url[5:]  # Remove 's3://'
        elif remote_url.startswith("gcs://"):
            storage_type = "gcs"
            url_without_prefix = remote_url[6:]  # Remove 'gcs://'
        else:
            raise ValueError(f"Unsupported URL scheme in {remote_url}")

        # Split bucket and path
        parts: Final = url_without_prefix.split("/", 1)
        if len(parts) < 2:
            raise ValueError(
                f"Invalid URL format: {remote_url}. Expected: {storage_type}://bucket-name/path/to/module.instance"
            )

        bucket_name: Final = parts[0]
        path_and_module: Final = parts[1]

        # Extract module path and instance name
        # Example: "loggers/custom_callbacks.proxy_handler_instance"
        # Handle case where user accidentally includes .py extension
        if path_and_module.endswith(".py"):
            module_name_without_py: Final = path_and_module[:-3]  # Remove .py
            raise ValueError(
                f"Invalid URL format in {remote_url}. "
                f"Don't include '.py' extension and you must specify the instance name. "
                f"Expected format: {storage_type}://{bucket_name}/{module_name_without_py}.instance_name "
                f"(e.g., {storage_type}://{bucket_name}/{module_name_without_py}.proxy_handler_instance)"
            )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Format the URL as <storage>://bucket-name/path/to/module.instance, e.g. s3://my-bucket/handlers/my_module.proxy_handler_instance.

When it happens

Trigger: Thrown at litellm/proxy/types_utils/utils.py:99 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/523d66449f6ac9ba. Report an issue: GitHub.