BerriAI/litellm · error · ValueError

Cloud storage bucket name must not include a URI scheme or q

Error message

Cloud storage bucket name must not include a URI scheme or query

What it means

split_configured_cloud_bucket_name rejects bucket configuration values that contain '://', '?', or '#'. The setting must be a plain 'bucket' or 'bucket/prefix' string, not a full URI; the check prevents users from pasting a URL (with scheme or query string) where only a bucket name belongs.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:93

        raise ValueError("Cloud storage object name is required")
    if object_name.startswith("/"):
        raise ValueError("Cloud storage object name must be relative")
    if any(ord(char) < 32 or ord(char) == 127 for char in object_name):
        raise ValueError("Cloud storage object name contains control characters")
    segments: Final = object_name.split("/")
    if any(segment in {".", ".."} for segment in segments):
        raise ValueError("Cloud storage object name contains an invalid path segment")
    if "" in segments[:-1]:
        raise ValueError("Cloud storage object name contains an invalid path segment")


def split_configured_cloud_bucket_name(bucket_name: str) -> tuple[str, str]:
    if not isinstance(bucket_name, str) or not bucket_name.strip():
        raise ValueError("Cloud storage bucket name is required")

    bucket_name = bucket_name.strip()
    if "://" in bucket_name or "?" in bucket_name or "#" in bucket_name:
        raise ValueError("Cloud storage bucket name must not include a URI scheme or query")
    if any(ord(char) < 32 or ord(char) == 127 for char in bucket_name):
        raise ValueError("Cloud storage bucket name contains control characters")

    bucket, _, prefix = bucket_name.partition("/")
    if not bucket:
        raise ValueError("Cloud storage bucket name is required")
    if "\\" in bucket:
        raise ValueError("Cloud storage bucket name contains an invalid separator")

    prefix = prefix.strip("/")
    if prefix:
        _validate_cloud_object_path(prefix)

    return bucket, prefix


def encode_gcs_object_name_for_url(object_name: str) -> str:
    return quote(unquote(object_name), safe="")

View on GitHub (pinned to 6c2dcb801b)

Solutions

Strip the scheme and any query/fragment: use just the bare bucket name, optionally with an object prefix ('my-bucket/my-prefix').
For GCS console URLs, extract the middle host component, e.g. 'gs://my-bucket/p' -> 'my-bucket/p'.
Add a startup assertion that the configured value contains no '://', '?', or '#' so misconfigurations surface at deploy time.

Example fix

# before
GCS_BUCKET="gs://my-team-bucket"  # raises

# after
GCS_BUCKET="my-team-bucket"              # bare bucket
# or with prefix:
GCS_BUCKET="my-team-bucket/litellm-files"

Defensive patterns

Strategy: validation

Validate before calling

def is_plain_bucket_setting(value: str) -> bool:
    v = value.strip()
    return bool(v) and "://" not in v and "?" not in v and "#" not in v

assert is_plain_bucket_setting("my-bucket/logs")
assert not is_plain_bucket_setting("gs://my-bucket")

Type guard

def is_plain_bucket_setting(value: object) -> bool:
    return (
        isinstance(value, str)
        and bool(value.strip())
        and all(t not in value for t in ("://", "?", "#"))
    )

Try / catch

try:
    bucket, prefix = split_configured_cloud_bucket_name(cfg)
except ValueError as e:
    raise ConfigError(f"Fix bucket setting (use 'bucket' or 'bucket/prefix'): {e}") from e

Prevention

Document the exact expected form ('bucket' or 'bucket/prefix') next to the env var.
Never paste console URLs into bucket fields; strip to the bare name first.
Assert no '://'/'?'/'#' in the value during config load.

When it happens

Trigger: Configuring the bucket as 'gs://my-bucket', 'https://my-bucket.storage.googleapis.com', or 'my-bucket?region=us' instead of 'my-bucket' or 'my-bucket/optional-prefix'. The partition('/') then can never produce a sane bucket, so litellm fails fast.

Common situations: Copying a bucket URL from the GCP/Azure console and pasting it straight into the env var or config.yaml; switching docs examples that show gs:// URIs into a field that expects a bare name; CI config templating a full endpoint URL into the bucket field.

Related errors

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