BerriAI/litellm · error · ValueError

Invalid URL format in {remote_url}. Don't include '.py' exte

Error message

Invalid URL format in {remote_url}. Don't include '.py' extension and you must specify the instance name. Expected format: {storage_type}://{bucket_name}/{module_name_without_py}.instance_name (e.g., {storage_type}://{bucket_name}/{module_name_without_py}.proxy_handler_instance)

What it means

Error "Invalid URL format in {remote_url}. Don't include '.py' extension and you must specify the instance name. Expected format: {storage_type}://{bucket_name}/{module_name_without_py}.instance_name (e.g., {storage_type}://{bucket_name}/{module_name_without_py}.proxy_handler_instance)" thrown in BerriAI/litellm.

Source

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

        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)"
            )

        # Split by last dot to separate module from instance
        module_parts: Final = path_and_module.split(".")
        if len(module_parts) < 2:
            raise ValueError(f"Invalid module specification in {remote_url}. Expected: path/to/module.instance_name")

        instance_name: Final = module_parts[-1]
        module_path: Final = ".".join(module_parts[:-1])

        # Create object key (file path in bucket)
        object_key: Final = f"{module_path}.py"

        verbose_proxy_logger.debug(

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Remove the '.py' extension and append the instance name, e.g. s3://bucket/module_name.instance_name.

When it happens

Trigger: Thrown at litellm/proxy/types_utils/utils.py:111 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/be94f08d52ed1db4. Report an issue: GitHub.