fix: make sure gcs_bucket_name passes

[Sameerlite]

Relevant issues

Fixes LIT-1860

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature
🐛 Bug Fix
🧹 Refactoring
📖 Documentation
🚄 Infrastructure
✅ Test

Changes

How to use:

model_list:
  - model_name: gemini-2.5-flash-lite
    litellm_params:
      model: vertex_ai/gemini-2.5-flash-lite
      gcs_bucket_name: litellm-proxy-file-uploads-prd-14526df1
      vertex_project: litellm-proxy-prd-14526df1

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 5, 2026 2:24pm

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds support for passing gcs_bucket_name through the router's litellm_metadata to enable GCS bucket configuration for Vertex AI file operations. The change allows gcs_bucket_name to be extracted from the router data and passed down to the Vertex AI files transformation layer.

Key Changes:

• Modified router.py to add gcs_bucket_name from request data into kwargs_copy["litellm_metadata"] before calling litellm.acreate_file()
• Updated VertexAIFilesConfig.get_complete_file_url() to check litellm_metadata for gcs_bucket_name as a fallback

Issues Found:

• Critical: Using .pop() in transformation.py:168 mutates the litellm_metadata dictionary, which can cause the gcs_bucket_name to be missing if the same dictionary is reused elsewhere (e.g., in retry logic or subsequent function calls)
• Minor: The code in router.py:3734 assumes litellm_metadata exists in kwargs_copy without defensive initialization, though _update_kwargs_with_deployment should handle this via setdefault

Confidence Score: 2/5

• This PR has a critical bug that will cause issues when the dictionary is reused
• The .pop() usage in transformation.py mutates shared state and will cause bugs in scenarios where litellm_params is reused (retries, fallbacks, or subsequent operations). This is a production-impacting bug that needs to be fixed before merge.
• Pay close attention to litellm/llms/vertex_ai/files/transformation.py:168 - the .pop() must be changed to .get() to avoid mutating shared state

Important Files Changed

Filename	Overview
litellm/llms/vertex_ai/files/transformation.py	Added fallback to retrieve gcs_bucket_name from litellm_metadata, but uses .pop() which mutates the dictionary
litellm/router.py	Added logic to pass gcs_bucket_name through litellm_metadata, potential KeyError risk if dictionary not initialized

Sequence Diagram

sequenceDiagram
    participant Client
    participant Router
    participant LiteLLM
    participant VertexAIConfig
    participant GCS

    Client->>Router: acreate_file(gcs_bucket_name="my-bucket", ...)
    Router->>Router: create_file_for_deployment()
    Router->>Router: _update_kwargs_with_deployment()<br/>(initializes litellm_metadata)
    
    alt gcs_bucket_name in data
        Router->>Router: kwargs_copy["litellm_metadata"]["gcs_bucket_name"] = data["gcs_bucket_name"]
    end
    
    Router->>LiteLLM: litellm.acreate_file(**data, **kwargs_copy)
    LiteLLM->>VertexAIConfig: get_complete_file_url(litellm_params)
    
    VertexAIConfig->>VertexAIConfig: Check bucket_name sources:<br/>1. litellm_params.get("bucket_name")<br/>2. litellm_params.get("litellm_metadata", {}).pop("gcs_bucket_name")<br/>3. os.getenv("GCS_BUCKET_NAME")
    
    Note over VertexAIConfig: ⚠️ .pop() mutates litellm_metadata!<br/>Subsequent access will fail
    
    VertexAIConfig->>LiteLLM: Return GCS URL
    LiteLLM->>GCS: Upload file to GCS bucket
    GCS->>LiteLLM: File uploaded
    LiteLLM->>Router: File object
    Router->>Client: File object

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

.pop() mutates litellm_metadata by removing the key, which causes issues if litellm_params is reused. Use .get() instead.

Suggested change

	bucket_name = litellm_params.get("bucket_name") or litellm_params.get("litellm_metadata", {}).pop("gcs_bucket_name", None) or os.getenv("GCS_BUCKET_NAME")
	bucket_name = litellm_params.get("bucket_name") or litellm_params.get("litellm_metadata", {}).get("gcs_bucket_name") or os.getenv("GCS_BUCKET_NAME")

Prompt To Fix With AI

This is a comment left during a code review.
Path: litellm/llms/vertex_ai/files/transformation.py
Line: 168:168

Comment:
`.pop()` mutates `litellm_metadata` by removing the key, which causes issues if `litellm_params` is reused. Use `.get()` instead.

```suggestion
        bucket_name = litellm_params.get("bucket_name") or litellm_params.get("litellm_metadata", {}).get("gcs_bucket_name") or os.getenv("GCS_BUCKET_NAME")
```

How can I resolve this? If you propose a fix, please make it concise.

[jquinter]

Hey @Sameerlite, thanks for working on this! I traced through the full call chain and I think there's a much simpler fix available.

Root cause

The gcs_bucket_name value from your YAML config already flows through to get_complete_file_url in transformation.py. Here's the path:

1. router.py:3688 — data = deployment["litellm_params"].copy() picks up gcs_bucket_name (it's a defined field in litellm/types/router.py:210)
2. router.py:3721-3728 — litellm.acreate_file(**{**data, ...}) passes it as a kwarg
3. files/main.py:124 — litellm_params_dict = dict(**kwargs) captures it
4. files/main.py:171 — base_llm_http_handler.create_file(litellm_params=litellm_params_dict, ...) forwards it
5. llm_http_handler.py:2862 — provider_config.get_complete_file_url(..., litellm_params=litellm_params, ...) passes it to your transformation

The problem is just that line 168 of transformation.py looks for "bucket_name" but the config key is "gcs_bucket_name":

# Current code — misses the config value:
bucket_name = litellm_params.get("bucket_name") or os.getenv("GCS_BUCKET_NAME")

Suggested fix

A one-liner in litellm/llms/vertex_ai/files/transformation.py:168:

bucket_name = litellm_params.get("bucket_name") or litellm_params.get("gcs_bucket_name") or os.getenv("GCS_BUCKET_NAME")

This means you don't need the router-level plumbing through litellm_metadata at all, and you can drop the # noqa: PLR0915 suppression.

Bug in current PR

Also a heads-up: the .pop() on line 168 of the current diff will mutate the litellm_metadata dict in place, which would cause gcs_bucket_name to go missing on retries or fallbacks. If you do keep the litellm_metadata approach for any reason, make sure to use .get() instead of .pop().

Hope this helps!

[Sameerlite]

@jquinter , if you check i have added a Todo in this PR, feel free to do that. Actually the issue is, after step 2, the gcs_bucket_name is not present in step 3. It gets removed in between somewhere but I am not able to pinpoint where. Hence I had added it like this. If you want, you can try this out. That's why i am popping it once i get it, because should not be in there ideally