{"record":{"id":"0befcedc1a8866ce","repo":"BerriAI/litellm","slug":"cloud-storage-bucket-name-contains-an-invalid-sepa","errorCode":null,"errorMessage":"Cloud storage bucket name contains an invalid separator","messagePattern":"Cloud storage bucket name contains an invalid separator","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/cloud_storage_security.py","lineNumber":101,"sourceCode":"    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=\"\")\n\n\ndef encode_s3_object_key_for_url(object_key: str) -> str:\n    return quote(unquote(object_key), safe=\"/\")\n\n\ndef should_allow_legacy_cloud_file_ids(\n    litellm_params: Mapping[str, Any] | None = None,","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/cloud_storage_security.py#L83-L119","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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('\\\\', '/')."],"exampleFix":"# before\nbucket_cfg = os.path.join(\"my-bucket\", \"logs\")   # 'my-bucket\\\\logs' on Windows -> raises\n\n# after\nbucket_cfg = \"/\".join([\"my-bucket\", \"logs\"])    # 'my-bucket/logs'","handlingStrategy":"validation","validationCode":"def sanitize_bucket_cfg(cfg: str) -> str:\n    return cfg.replace(\"\\\\\", \"/\")  # Windows-built paths -> cloud form\n\ncfg = sanitize_bucket_cfg(os.environ[\"GCS_BUCKET\"])","typeGuard":"def has_no_backslash_in_bucket(value: object) -> bool:\n    if not isinstance(value, str):\n        return False\n    bucket = value.strip().partition(\"/\")[0]\n    return \"\\\\\" not in bucket","tryCatchPattern":"try:\n    split_configured_cloud_bucket_name(cfg)\nexcept ValueError as e:\n    if \"invalid separator\" in str(e):\n        cfg = cfg.replace(\"\\\\\", \"/\")\n        bucket, prefix = split_configured_cloud_bucket_name(cfg)  # retry once, then surface\n    else:\n        raise","preventionTips":["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."],"tags":["cloud-storage","config","windows","path-separator","gcs"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}