Bug Description

When Claude Code (or any client) sends cache_control with scope field via the Anthropic Messages passthrough endpoint (/v1/messages) to Vertex AI, the request fails with:

system.1.cache_control.ephemeral.scope: Extra inputs are not permitted

Vertex AI does not support the scope field in cache_control (the prompt-caching-scope-2026-01-05 beta). LiteLLM already correctly filters out the prompt-caching-scope-2026-01-05 beta header for Vertex AI in anthropic_beta_headers_config.json (set to null), but does not strip the scope field from the request body.

Root Cause

In PR #22867, _remove_scope_from_cache_control was added for Bedrock and Azure AI, but Vertex AI was missed.

• litellm/llms/azure_ai/anthropic/messages_transformation.py — has _remove_scope_from_cache_control ✅
• litellm/llms/bedrock/messages/invoke_transformations/anthropic_claude3_transformation.py — has cache_control.pop("scope", None) ✅
• litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/experimental_pass_through/transformation.py — missing ❌

Steps to Reproduce

1. Configure LiteLLM with a Vertex AI Claude model
2. Send a request to /v1/messages with cache_control containing scope:

curl http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: <key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-scope-2026-01-05" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 100,
    "system": [
      {"type": "text", "text": "You are helpful"},
      {"type": "text", "text": "Be concise", "cache_control": {"type": "ephemeral", "scope": "turn"}}
    ],
    "messages": [{"role": "user", "content": "hi"}]
  }'

Expected: scope stripped from body, request succeeds
Actual: 400 error cache_control.ephemeral.scope: Extra inputs are not permitted

Suggested Fix

Add _remove_scope_from_cache_control to VertexAIPartnerModelsAnthropicMessagesConfig in litellm/llms/vertex_ai/vertex_ai_partner_models/anthropic/experimental_pass_through/transformation.py, matching the Azure AI implementation:

def _remove_scope_from_cache_control(self, anthropic_messages_request: Dict) -> None:
    def _sanitize(cache_control):
        if isinstance(cache_control, dict):
            cache_control.pop("scope", None)

    def _process_content_list(content):
        for item in content:
            if isinstance(item, dict) and "cache_control" in item:
                _sanitize(item["cache_control"])

    if "system" in anthropic_messages_request:
        system = anthropic_messages_request["system"]
        if isinstance(system, list):
            _process_content_list(system)

    if "messages" in anthropic_messages_request:
        for message in anthropic_messages_request["messages"]:
            if isinstance(message, dict) and "content" in message:
                content = message["content"]
                if isinstance(content, list):
                    _process_content_list(content)

Then call self._remove_scope_from_cache_control(anthropic_messages_request) in transform_anthropic_messages_request().

Related

• PR #22867 — fix for Bedrock and Azure AI (Vertex AI was missed)
• PR #20058 — filtered prompt-caching-scope-2026-01-05 header for Vertex AI
• Issue #19984 — original beta header issue

Environment

• LiteLLM version: v1.81.14-stable (also reproducible on latest main)
• Provider: vertex_ai
• Client: Claude Code