{"record":{"id":"30db96df1be96d6a","repo":"BerriAI/litellm","slug":"cloud-storage-bucket-name-is-required","errorCode":null,"errorMessage":"Cloud storage bucket name is required","messagePattern":"Cloud storage bucket name is required","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/cloud_storage_security.py","lineNumber":89,"sourceCode":"\n\ndef _validate_cloud_object_path(object_name: str) -> None:\n    if not object_name:\n        raise ValueError(\"Cloud storage object name is required\")\n    if object_name.startswith(\"/\"):\n        raise ValueError(\"Cloud storage object name must be relative\")\n    if any(ord(char) < 32 or ord(char) == 127 for char in object_name):\n        raise ValueError(\"Cloud storage object name contains control characters\")\n    segments: Final = object_name.split(\"/\")\n    if any(segment in {\".\", \"..\"} for segment in segments):\n        raise ValueError(\"Cloud storage object name contains an invalid path segment\")\n    if \"\" in segments[:-1]:\n        raise ValueError(\"Cloud storage object name contains an invalid path segment\")\n\n\ndef split_configured_cloud_bucket_name(bucket_name: str) -> tuple[str, str]:\n    if not isinstance(bucket_name, str) or not bucket_name.strip():\n        raise ValueError(\"Cloud storage bucket name is required\")\n\n    bucket_name = bucket_name.strip()\n    if \"://\" in bucket_name or \"?\" in bucket_name or \"#\" in bucket_name:\n        raise ValueError(\"Cloud storage bucket name must not include a URI scheme or query\")\n    if any(ord(char) < 32 or ord(char) == 127 for char in bucket_name):\n        raise ValueError(\"Cloud storage bucket name contains control characters\")\n\n    bucket, _, prefix = bucket_name.partition(\"/\")\n    if not bucket:\n        raise ValueError(\"Cloud storage bucket name is required\")\n    if \"\\\\\" in bucket:\n        raise ValueError(\"Cloud storage bucket name contains an invalid separator\")\n\n    prefix = prefix.strip(\"/\")\n    if prefix:\n        _validate_cloud_object_path(prefix)\n\n    return bucket, prefix","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/cloud_storage_security.py#L71-L107","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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`).","Check for typos in the env var name and confirm the value survived interpolation (docker-compose/Kubernetes secrets often render empty)."],"exampleFix":"# before\nbucket = os.environ.get(\"GCS_BUCKET\", \"\")  # unset -> ''\n\n# after\nbucket = os.environ.get(\"GCS_BUCKET\")\nif not bucket or not bucket.strip():\n    raise RuntimeError(\"GCS_BUCKET must be set to a non-empty bucket name\")","handlingStrategy":"validation","validationCode":"def get_bucket_or_fail(env_var: str = \"GCS_BUCKET\") -> str:\n    value = os.environ.get(env_var)\n    if not isinstance(value, str) or not value.strip():\n        raise RuntimeError(f\"{env_var} must be set to a non-empty bucket name\")\n    return value.strip()","typeGuard":"def is_usable_bucket_setting(value: object) -> bool:\n    return isinstance(value, str) and bool(value.strip())","tryCatchPattern":"from litellm.litellm_core_utils.cloud_storage_security import split_configured_cloud_bucket_name\ntry:\n    bucket, prefix = split_configured_cloud_bucket_name(bucket_name)\nexcept ValueError as e:\n    # fail startup with actionable config error\n    logger.error(\"Storage bucket misconfigured: %s\", e)\n    raise SystemExit(1)","preventionTips":["Validate required storage env vars at process startup, not lazily on first request.","Use a config schema/defaults checker that rejects empty strings for bucket settings.","Integration-test the deployment with the same env source used in production."],"tags":["cloud-storage","config","gcs","validation"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}