BerriAI/litellm · error · ValueError

Cloud storage bucket name contains an invalid separator

Error message

Cloud storage bucket name contains an invalid separator

What it means

split_configured_cloud_bucket_name raises this when the bucket component (the part before the first '/') contains a backslash. Cloud storage bucket names use '/' as the only separator, so a '\\' signals a Windows-style or malformed path was supplied instead of a bucket name.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:101

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


def encode_s3_object_key_for_url(object_key: str) -> str:
    return quote(unquote(object_key), safe="/")


def should_allow_legacy_cloud_file_ids(
    litellm_params: Mapping[str, Any] | None = None,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Replace backslashes with forward slashes and ensure only 'bucket/prefix' form remains ('my-bucket/logs').
Never build the value with os.path.join; use a literal 'bucket/prefix' string or '/'.join(parts).
Normalize on read if the value may come from Windows tooling: configured.replace('\\', '/').

Example fix

# before
bucket_cfg = os.path.join("my-bucket", "logs")   # 'my-bucket\\logs' on Windows -> raises

# after
bucket_cfg = "/".join(["my-bucket", "logs"])    # 'my-bucket/logs'

Defensive patterns

Strategy: validation

Validate before calling

def sanitize_bucket_cfg(cfg: str) -> str:
    return cfg.replace("\\", "/")  # Windows-built paths -> cloud form

cfg = sanitize_bucket_cfg(os.environ["GCS_BUCKET"])

Type guard

def has_no_backslash_in_bucket(value: object) -> bool:
    if not isinstance(value, str):
        return False
    bucket = value.strip().partition("/")[0]
    return "\\" not in bucket

Try / catch

try:
    split_configured_cloud_bucket_name(cfg)
except ValueError as e:
    if "invalid separator" in str(e):
        cfg = cfg.replace("\\", "/")
        bucket, prefix = split_configured_cloud_bucket_name(cfg)  # retry once, then surface
    else:
        raise

Prevention

Never use os.path.join to build cloud bucket strings; use '/'.join(...).
Normalize backslashes to slashes when configs may originate on Windows.
CI-lint config values for backslash separators.

When it happens

Trigger: Configured value like 'my-bucket\\logs' or a Windows path 'C:\\buckets\\my-bucket' pasted into the bucket setting; the bucket part before the first '/' contains '\\' and the guard fires.

Common situations: Developers on Windows building config paths with os.path.join (yielding '\\') and writing the result into the bucket env var; docs/scripts authored on Windows committed with backslash separators.

Related errors

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