BerriAI/litellm · error · ValueError

file_id bucket does not match the configured storage bucket

Error message

file_id bucket does not match the configured storage bucket

What it means

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.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:152

def validate_managed_cloud_file_id(
    file_id: str,
    scheme: str,
    configured_bucket_name: str,
    allowed_object_prefixes: Sequence[str],
    allow_legacy_cloud_file_ids: bool = False,
) -> tuple[str, str]:
    decoded_file_id: Final = unquote(file_id)
    if not decoded_file_id.startswith(scheme):
        raise ValueError(f"file_id must be a {scheme} URI")

    full_path: Final = decoded_file_id[len(scheme) :]
    if "/" not in full_path:
        raise ValueError("file_id must include a cloud storage object name")

    bucket_name, object_name = full_path.split("/", 1)
    configured_bucket, configured_prefix = split_configured_cloud_bucket_name(configured_bucket_name)
    if bucket_name != configured_bucket:
        raise ValueError("file_id bucket does not match the configured storage bucket")

    _validate_cloud_object_path(object_name)
    allowed_prefixes = tuple(allowed_object_prefixes)
    if configured_prefix:
        allowed_prefixes = tuple(f"{configured_prefix.rstrip('/')}/{prefix}" for prefix in allowed_prefixes)

    if object_name.startswith(allowed_prefixes):
        return bucket_name, object_name

    if allow_legacy_cloud_file_ids:
        if configured_prefix and not object_name.startswith(f"{configured_prefix.rstrip('/')}/"):
            raise ValueError("file_id object does not match the configured storage prefix")
        return bucket_name, object_name

    raise ValueError("file_id must reference a LiteLLM-managed storage object")

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Re-upload/register the file against the currently configured bucket and use the new returned URI.
2. If the old bucket is the correct one, update the deployment's bucket configuration to match it and restart.
3. If you genuinely need multiple buckets, run separate deployments/configs per bucket rather than sending foreign-bucket ids to one proxy.

Example fix

# before
# proxy configured: GCS_BUCKET=my-bucket
file_id = "gs://old-bucket/litellm/x.json"   # bucket mismatch

# after
file_id = "gs://my-bucket/litellm/x.json"    # matches configured bucket
# (or set GCS_BUCKET=old-bucket if that is the source of truth)

def bucket_matches_config(file_id: str, configured: str, scheme: str = "gs://") -> bool:
    fid_bucket = unquote(file_id)[len(scheme):].split("/", 1)[0]
    cfg_bucket = configured.strip().partition("/")[0]
    return fid_bucket == cfg_bucket

def references_configured_bucket(file_id: object, configured: str, scheme: str = "gs://") -> bool:
    if not isinstance(file_id, str) or not file_id.startswith(scheme):
        return False
    return unquote(file_id)[len(scheme):].split("/", 1)[0] == configured.strip().partition("/")[0]

try:
    validate_managed_cloud_file_id(fid, scheme, cfg, prefixes)
except ValueError as e:
    if "does not match the configured storage bucket" in str(e):
        # stale id from another bucket: re-register the file, do not widen config blindly
        fid = reupload_and_get_managed_uri(local_copy)\n    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• file_id must be a {scheme} URI
• file_id object does not match the configured storage prefix
• file_id must reference a LiteLLM-managed storage object
• Cloud storage bucket name is required
• Cloud storage bucket name must not include a URI scheme or q

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