{"record":{"id":"099e16fa2c2e0f09","repo":"BerriAI/litellm","slug":"file-id-bucket-does-not-match-the-configured-stora","errorCode":null,"errorMessage":"file_id bucket does not match the configured storage bucket","messagePattern":"file_id bucket does not match the configured storage bucket","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/cloud_storage_security.py","lineNumber":152,"sourceCode":"def validate_managed_cloud_file_id(\n    file_id: str,\n    scheme: str,\n    configured_bucket_name: str,\n    allowed_object_prefixes: Sequence[str],\n    allow_legacy_cloud_file_ids: bool = False,\n) -> tuple[str, str]:\n    decoded_file_id: Final = unquote(file_id)\n    if not decoded_file_id.startswith(scheme):\n        raise ValueError(f\"file_id must be a {scheme} URI\")\n\n    full_path: Final = decoded_file_id[len(scheme) :]\n    if \"/\" not in full_path:\n        raise ValueError(\"file_id must include a cloud storage object name\")\n\n    bucket_name, object_name = full_path.split(\"/\", 1)\n    configured_bucket, configured_prefix = split_configured_cloud_bucket_name(configured_bucket_name)\n    if bucket_name != configured_bucket:\n        raise ValueError(\"file_id bucket does not match the configured storage bucket\")\n\n    _validate_cloud_object_path(object_name)\n    allowed_prefixes = tuple(allowed_object_prefixes)\n    if configured_prefix:\n        allowed_prefixes = tuple(f\"{configured_prefix.rstrip('/')}/{prefix}\" for prefix in allowed_prefixes)\n\n    if object_name.startswith(allowed_prefixes):\n        return bucket_name, object_name\n\n    if allow_legacy_cloud_file_ids:\n        if configured_prefix and not object_name.startswith(f\"{configured_prefix.rstrip('/')}/\"):\n            raise ValueError(\"file_id object does not match the configured storage prefix\")\n        return bucket_name, object_name\n\n    raise ValueError(\"file_id must reference a LiteLLM-managed storage object\")\n","sourceCodeStart":134,"sourceCodeEnd":168,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/cloud_storage_security.py#L134-L168","documentation":"validate_managed_cloud_file_id splits the file_id into bucket and object, then compares the bucket against the configured bucket (itself parsed by split_configured_cloud_bucket_name). A mismatch raises this error: the id is well-formed but points at a different bucket than the one this deployment is allowed to touch. This confines managed file access to the single configured bucket.","triggerScenarios":"file_id = 'gs://other-team-bucket/file.json' while the proxy is configured with bucket 'my-bucket'; also stale ids after migrating to a new bucket name, or cross-environment leakage (prod id sent to a staging proxy configured with the staging bucket).","commonSituations":"Repointing the deployment to a new bucket but clients still replay cached file ids; multi-tenant setups where teams share a proxy but have separate buckets (only one is configurable); typos in the bucket portion of hand-built URIs.","solutions":["Re-upload/register the file against the currently configured bucket and use the new returned URI.","If the old bucket is the correct one, update the deployment's bucket configuration to match it and restart.","If you genuinely need multiple buckets, run separate deployments/configs per bucket rather than sending foreign-bucket ids to one proxy."],"exampleFix":"# before\n# proxy configured: GCS_BUCKET=my-bucket\nfile_id = \"gs://old-bucket/litellm/x.json\"   # bucket mismatch\n\n# after\nfile_id = \"gs://my-bucket/litellm/x.json\"    # matches configured bucket\n# (or set GCS_BUCKET=old-bucket if that is the source of truth)","handlingStrategy":"validation","validationCode":"def bucket_matches_config(file_id: str, configured: str, scheme: str = \"gs://\") -> bool:\n    fid_bucket = unquote(file_id)[len(scheme):].split(\"/\", 1)[0]\n    cfg_bucket = configured.strip().partition(\"/\")[0]\n    return fid_bucket == cfg_bucket","typeGuard":"def references_configured_bucket(file_id: object, configured: str, scheme: str = \"gs://\") -> bool:\n    if not isinstance(file_id, str) or not file_id.startswith(scheme):\n        return False\n    return unquote(file_id)[len(scheme):].split(\"/\", 1)[0] == configured.strip().partition(\"/\")[0]","tryCatchPattern":"try:\n    validate_managed_cloud_file_id(fid, scheme, cfg, prefixes)\nexcept ValueError as e:\n    if \"does not match the configured storage bucket\" in str(e):\n        # stale id from another bucket: re-register the file, do not widen config blindly\n        fid = reupload_and_get_managed_uri(local_copy)\\n    raise","preventionTips":["On bucket migrations, plan id re-issuance for stored references.","Keep one bucket per deployment config; separate environments by config.","Compare the bucket in stored ids against config during smoke tests."],"tags":["file-upload","cloud-storage","bucket-mismatch","config","security"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}