BerriAI/litellm · error · ValueError

Invalid module specification in {remote_url}. Expected: path

Error message

Invalid module specification in {remote_url}. Expected: path/to/module.instance_name

What it means

The path portion of the remote URL has no dot separating module path from instance name (or ends without an instance), so module.instance cannot be split. The URL must name both the Python module and the exported instance, e.g. s3://bucket/loggers/custom_callbacks.proxy_handler_instance.

Source

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

        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(
            "Loading custom logger from %s: bucket=%s, object_key=%s, instance=%s",
            storage_type,
            bucket_name,
            object_key,
            instance_name,
        )

        import tempfile

        # Create temporary file for the downloaded module using the actual module name

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Specify the module as path/to/module.instance_name after the bucket name.

When it happens

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