BerriAI/litellm · error · ValueError

file_id must be a {scheme} URI

Error message

file_id must be a {scheme} URI

What it means

validate_managed_cloud_file_id raises this when the URL-decoded file_id does not start with the expected scheme (e.g. 'gs://'). LiteLLM-managed file references are URIs of the form '<scheme><bucket>/<object>'; anything else — a bare filename or another provider's id — is rejected before any storage access, as a security check that only managed objects are fetched.

Source

Thrown at litellm/litellm_core_utils/cloud_storage_security.py:143

            value = cast(Mapping[str, Any], trusted_model_credentials).get("allow_legacy_cloud_file_ids")

    if isinstance(value, bool):
        return value
    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

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Prefix the reference with the correct scheme and managed path: 'gs://<configured-bucket>/<object-under-allowed-prefix>'.
2. If you have a raw provider file id, first upload/register the file through litellm's file management so you get back a managed URI, then use that.
3. Double-check you are calling the endpoint matching your configured backend (GCS vs Azure) so the scheme lines up.

Example fix

# before
file_id = "file-abc123"           # provider-native id -> raises

# after
file_id = "gs://my-bucket/litellm/abc123.json"  # managed <scheme>bucket/object URI

def is_managed_file_id(file_id: str, scheme: str = "gs://") -> bool:
    from urllib.parse import unquote
    return unquote(file_id).startswith(scheme)

from urllib.parse import unquote

def is_managed_file_id(file_id: object, scheme: str = "gs://") -> bool:
    """Narrow to litellm-managed cloud URIs like gs://bucket/object."""
    if not isinstance(file_id, str):
        return False
    d = unquote(file_id)
    return d.startswith(scheme) and "/" in d[len(scheme):]

from litellm.litellm_core_utils.cloud_storage_security import validate_managed_cloud_file_id
try:
    bucket, obj = validate_managed_cloud_file_id(fid, "gs://", cfg_bucket, allowed_prefixes)
except ValueError as e:
    return HTTP 400 to the caller with the validator's message — do not retry

When it happens

Trigger: Passing 'file-abc123' (an OpenAI-style file id) or 'reports/q3.csv' where the API expects 'gs://my-bucket/...'; also passing an Azure 'https://...' URL when the deployment is configured for GCS (scheme mismatch). The decoded string simply fails decoded_file_id.startswith(scheme).

Common situations: Migrating code from direct OpenAI files API to litellm managed files without rewriting stored file ids; storing provider-native ids in your DB and replaying them to litellm endpoints; percent-encoding that decodes to a scheme-less value.

Related errors

• file_id must include a cloud storage object name
• file_id bucket does not match the configured storage bucket
• file_id must reference a LiteLLM-managed storage object
• Invalid file path {file_path!r}: path traversal detected
• MAVVRIK_API_ENDPOINT must be an HTTPS URL

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