{"record":{"id":"d0619c4a1e065317","repo":"BerriAI/litellm","slug":"file-id-object-does-not-match-the-configured-stora","errorCode":null,"errorMessage":"file_id object does not match the configured storage prefix","messagePattern":"file_id object does not match the configured storage prefix","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"litellm/litellm_core_utils/cloud_storage_security.py","lineNumber":164,"sourceCode":"    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":146,"sourceCodeEnd":168,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/cloud_storage_security.py#L146-L168","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Alternatively extend allowed_object_prefixes to include the legacy folder if the deployment supports configuring it."],"exampleFix":"# before\n# config: my-bucket/teams/alpha ; legacy ids enabled\nfile_id = \"gs://my-bucket/legacy/x.json\"   # not under teams/alpha\n\n# after\nfile_id = \"gs://my-bucket/teams/alpha/x.json\"\n# or change config bucket to 'my-bucket' (no prefix) to accept legacy layout","handlingStrategy":"validation","validationCode":"def object_under_configured_prefix(file_id: str, configured: str, scheme: str = \"gs://\") -> bool:\n    cfg_bucket, _, cfg_prefix = configured.strip().partition(\"/\")\n    bucket, obj = unquote(file_id)[len(scheme):].split(\"/\", 1)\n    return bucket == cfg_bucket and (not cfg_prefix or obj.startswith(cfg_prefix.strip('/') + '/'))","typeGuard":"def is_legacy_compatible_uri(v: object, configured: str, scheme: str = \"gs://\") -> bool:\n    if not isinstance(v, str):\n        return False\n    try:\n        bucket, obj = unquote(v)[len(scheme):].split(\"/\", 1)\n    except ValueError:\n        return False\n    cfg_bucket, _, cfg_prefix = configured.strip().partition(\"/\")\n    return bucket == cfg_bucket and (not cfg_prefix or obj.startswith(cfg_prefix.strip('/') + '/'))","tryCatchPattern":"try:\n    validate_managed_cloud_file_id(fid, scheme, cfg, prefixes, allow_legacy_cloud_file_ids=True)\nexcept ValueError as e:\n    if \"configured storage prefix\" in str(e):\n        migrate_object_under_prefix(fid)  # copy to configured prefix, update reference\n    raise","preventionTips":["When introducing a bucket prefix into config, migrate legacy objects under it.","Time-box allow_legacy_cloud_file_ids to the migration window, then disable.","Keep a mapping table of legacy->new object keys during migration."],"tags":["file-upload","cloud-storage","prefix","legacy-migration","config"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}