{"record":{"id":"52094819c0c0dc1c","repo":"BerriAI/litellm","slug":"cloud-storage-bucket-name-must-not-include-a-uri-s","errorCode":null,"errorMessage":"Cloud storage bucket name must not include a URI scheme or query","messagePattern":"Cloud storage bucket name must not include a URI scheme or query","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/cloud_storage_security.py","lineNumber":93,"sourceCode":"        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\n\n\ndef encode_gcs_object_name_for_url(object_name: str) -> str:\n    return quote(unquote(object_name), safe=\"\")","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/cloud_storage_security.py#L75-L111","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nGCS_BUCKET=\"gs://my-team-bucket\"  # raises\n\n# after\nGCS_BUCKET=\"my-team-bucket\"              # bare bucket\n# or with prefix:\nGCS_BUCKET=\"my-team-bucket/litellm-files\"","handlingStrategy":"validation","validationCode":"def is_plain_bucket_setting(value: str) -> bool:\n    v = value.strip()\n    return bool(v) and \"://\" not in v and \"?\" not in v and \"#\" not in v\n\nassert is_plain_bucket_setting(\"my-bucket/logs\")\nassert not is_plain_bucket_setting(\"gs://my-bucket\")","typeGuard":"def is_plain_bucket_setting(value: object) -> bool:\n    return (\n        isinstance(value, str)\n        and bool(value.strip())\n        and all(t not in value for t in (\"://\", \"?\", \"#\"))\n    )","tryCatchPattern":"try:\n    bucket, prefix = split_configured_cloud_bucket_name(cfg)\nexcept ValueError as e:\n    raise ConfigError(f\"Fix bucket setting (use 'bucket' or 'bucket/prefix'): {e}\") from e","preventionTips":["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."],"tags":["cloud-storage","config","uri","gcs","validation"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}