BerriAI/litellm · error · ValueError

Cloud storage bucket name is required

Error message

Cloud storage bucket name is required

What it means

split_configured_cloud_bucket_name raises this ValueError when the configured bucket name argument is not a string, or is empty/whitespace-only. LiteLLM requires a non-blank bucket setting before it can parse bucket and optional prefix, so this fires at configuration-parse time, not at request time.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:89


def _validate_cloud_object_path(object_name: str) -> None:
    if not object_name:
        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

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Set the bucket name in your environment/config (export the storage bucket variable or add it under the relevant cloud storage settings block) and restart.
  2. If set programmatically, verify the value is a non-empty str before passing it in (guard with `if not bucket_name or not bucket_name.strip(): raise/configure`).
  3. Check for typos in the env var name and confirm the value survived interpolation (docker-compose/Kubernetes secrets often render empty).

Example fix

# before
bucket = os.environ.get("GCS_BUCKET", "")  # unset -> ''

# after
bucket = os.environ.get("GCS_BUCKET")
if not bucket or not bucket.strip():
    raise RuntimeError("GCS_BUCKET must be set to a non-empty bucket name")
Defensive patterns

Strategy: validation

Validate before calling

def get_bucket_or_fail(env_var: str = "GCS_BUCKET") -> str:
    value = os.environ.get(env_var)
    if not isinstance(value, str) or not value.strip():
        raise RuntimeError(f"{env_var} must be set to a non-empty bucket name")
    return value.strip()

Type guard

def is_usable_bucket_setting(value: object) -> bool:
    return isinstance(value, str) and bool(value.strip())

Try / catch

from litellm.litellm_core_utils.cloud_storage_security import split_configured_cloud_bucket_name
try:
    bucket, prefix = split_configured_cloud_bucket_name(bucket_name)
except ValueError as e:
    # fail startup with actionable config error
    logger.error("Storage bucket misconfigured: %s", e)
    raise SystemExit(1)

Prevention

When it happens

Trigger: Calling split_configured_cloud_bucket_name('') , split_configured_cloud_bucket_name(' '), or passing None (fails the isinstance str check). Happens internally when a managed-files feature reads its bucket environment/config variable (e.g. GCS bucket for file management) and it is unset.

Common situations: Deploying the proxy without setting the storage bucket env var (e.g. LITELLM_*_BUCKET_NAME / cloud storage settings in config.yaml); variable name typo so the setting silently resolves to empty string; passing AWS_BUCKET_NAME / GCS bucket config of '' in a Helm chart.

Related errors

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