BerriAI/litellm · warning · ValueError

file_id object does not match the configured storage prefix

Error message

file_id object does not match the configured storage prefix

What it means

Raised in the legacy fallback branch of validate_managed_cloud_file_id: when the object is outside the allowed prefixes and allow_legacy_cloud_file_ids=True, litellm still requires the object to live under the configured bucket prefix (from 'bucket/prefix' config). If the object does not start with '<configured-prefix>/', this more specific error is thrown instead of the generic managed-object error.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:164

    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. Copy/migrate legacy objects under the configured prefix (gsutil cp then reference the new key), or re-upload via litellm so ids land in the allowed prefixes.
2. If the legacy objects must stay where they are, set the configured bucket name to the bare bucket (drop the '/prefix') so the prefix constraint disappears — accepting the wider scope.
3. Alternatively extend allowed_object_prefixes to include the legacy folder if the deployment supports configuring it.

Example fix

# before
# config: my-bucket/teams/alpha ; legacy ids enabled
file_id = "gs://my-bucket/legacy/x.json"   # not under teams/alpha

# after
file_id = "gs://my-bucket/teams/alpha/x.json"
# or change config bucket to 'my-bucket' (no prefix) to accept legacy layout

def object_under_configured_prefix(file_id: str, configured: str, scheme: str = "gs://") -> bool:
    cfg_bucket, _, cfg_prefix = configured.strip().partition("/")
    bucket, obj = unquote(file_id)[len(scheme):].split("/", 1)
    return bucket == cfg_bucket and (not cfg_prefix or obj.startswith(cfg_prefix.strip('/') + '/'))

def is_legacy_compatible_uri(v: object, configured: str, scheme: str = "gs://") -> bool:
    if not isinstance(v, str):
        return False
    try:
        bucket, obj = unquote(v)[len(scheme):].split("/", 1)
    except ValueError:
        return False
    cfg_bucket, _, cfg_prefix = configured.strip().partition("/")
    return bucket == cfg_bucket and (not cfg_prefix or obj.startswith(cfg_prefix.strip('/') + '/'))

try:
    validate_managed_cloud_file_id(fid, scheme, cfg, prefixes, allow_legacy_cloud_file_ids=True)
except ValueError as e:
    if "configured storage prefix" in str(e):
        migrate_object_under_prefix(fid)  # copy to configured prefix, update reference
    raise

When it happens

Trigger: Configured bucket value 'my-bucket/teams/alpha' (prefix 'teams/alpha'), legacy ids allowed, but file_id = 'gs://my-bucket/teams/beta/x.json' — object under the bucket yet not under the configured prefix, so the startswith check fails.

Common situations: Enabling allow_legacy_cloud_file_ids during a migration while the bucket config gained a prefix for the first time; historical objects uploaded before prefixes were introduced living at the bucket root or under other folders.

Related errors

• file_id bucket does not match the configured storage bucket
• 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
• Cloud storage bucket name contains control characters

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