What causes "file_id must include a cloud storage object name" in BerriAI/litellm?

Use the full managed URI including object name: 'gs://my-bucket/path/to/object.json'.

BerriAI/litellm · error · ValueError

file_id must include a cloud storage object name

Error message

file_id must include a cloud storage object name

What it means

In validate_managed_cloud_file_id, after stripping the scheme the remainder must contain at least one '/', because the managed format is '<scheme><bucket>/<object>'. This error means the id decoded to just a bucket (or bare token) with no object name — there is nothing to fetch and the split into bucket/object would be meaningless.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:147

    if isinstance(value, str):
        return value.strip().lower() in {"1", "true", "yes", "on"}
    return False


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

View on GitHub (pinned to 6c2dcb801b)

Solutions

Use the full managed URI including object name: 'gs://my-bucket/path/to/object.json'.
Audit where the id was produced — f-string or URL parsing that dropped everything after the bucket — and fix the producer.
When generating ids yourself, follow scheme + bucket + '/' + object and run a quick '/'-presence check before sending.

Example fix

# before
file_id = f"gs://{bucket}"                 # missing object part

# after
file_id = f"gs://{bucket}/{object_name}"   # e.g. gs://my-bucket/litellm/x.json

Defensive patterns

Strategy: type-guard

Validate before calling

from urllib.parse import unquote

def has_object_component(file_id: str, scheme: str = "gs://") -> bool:
    return "/" in unquote(file_id)[len(scheme):]

Type guard

def is_full_managed_uri(v: object, scheme: str = "gs://") -> bool:
    if not isinstance(v, str):
        return False
    rest = unquote(v)[len(scheme):]
    return "/" in rest and bool(rest.split("/", 1)[1])

Try / catch

try:
    validate_managed_cloud_file_id(fid, scheme, bucket, prefixes)
except ValueError as e:
    if "object name" in str(e):
        fid = f"{fid.rstrip('/')}/{default_object}"  # or ask caller for the full URI
    raise

Prevention

Always build ids as f"{scheme}{bucket}/{object}" — both parts mandatory.
Round-trip test id generation/parsing in CI.
Validate ids after any ETL that touches their string form.

When it happens

Trigger: file_id like 'gs://my-bucket' (scheme and bucket but no '/object'), or a value whose '/' was lost to encoding such as 'gs%3A%2F%2Fmy-bucket' decoding oddly. full_path = decoded[len(scheme):] contains no '/' and the guard fires.

Common situations: Truncating stored URIs at the first '/' during ETL; string-formatting bugs that drop the object portion (f"gs://{bucket}" instead of f"gs://{bucket}/{obj}"); users assuming the bucket alone identifies a file.

Related errors

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