Root cause

Date: February 13, 2026 Duration: ~3 hours Severity: High Status: Resolved

Note: This fix will be available starting from v1.81.13-nightly or higher of LiteLLM.

Summary

Claude Code began sending unsupported Anthropic beta headers to non-Anthropic providers (Bedrock, Azure AI, Vertex AI), causing invalid beta flag errors. LiteLLM was forwarding all beta headers without provider-specific validation. Users experienced request failures when routing Claude Code requests through LiteLLM to these providers.

• LLM calls to Anthropic: No impact.
• LLM calls to Bedrock/Azure/Vertex: Failed with invalid beta flag errors when unsupported headers were present.
• Cost tracking and routing: No impact.

{/* truncate */}

Background

Anthropic uses beta headers to enable experimental features in Claude. When Claude Code makes API requests, it includes headers like anthropic-beta: prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20. However, not all providers support all Anthropic beta features.

Before this incident, LiteLLM forwarded all beta headers to all providers without validation:

sequenceDiagram
    participant CC as Claude Code
    participant LP as LiteLLM (old behavior)
    participant Provider as Provider (Bedrock/Azure/Vertex)

    CC->>LP: Request with beta headers
    Note over CC,LP: anthropic-beta: header1,header2,header3

    LP->>Provider: Forward ALL headers (no validation)
    Note over LP,Provider: anthropic-beta: header1,header2,header3

    Provider-->>LP: ❌ Error: invalid beta flag
    LP-->>CC: Request fails

Requests succeeded for Anthropic (native support) but failed for other providers when Claude Code sent headers those providers didn't support.

Root cause

LiteLLM lacked provider-specific beta header validation. When Claude Code introduced new beta features or sent headers that specific providers didn't support, those headers were blindly forwarded, causing provider API errors.

Remediation

Now LiteLLM validates and transforms headers per-provider:

sequenceDiagram
    participant CC as Claude Code
    participant LP as LiteLLM (new behavior)
    participant Config as Beta Headers Config
    participant Provider as Provider (Bedrock/Azure/Vertex)

    CC->>LP: Request with beta headers
    Note over CC,LP: anthropic-beta: header1,header2,header3

    LP->>Config: Load header mapping for provider
    Config-->>LP: Returns mapping (header→value or null)

    Note over LP: Validate & Transform:<br/>1. Check if header exists in mapping<br/>2. Filter out null values<br/>3. Map to provider-specific names

    LP->>Provider: Request with filtered & mapped headers
    Note over LP,Provider: anthropic-beta: mapped-header2<br/>(header1, header3 filtered out)

    Provider-->>LP: ✅ Success response
    LP-->>CC: Response

Dynamic configuration updates

A key improvement is zero-downtime configuration updates. When Anthropic releases new beta features, users can update their configuration without restarting:

# Manually trigger reload (no restart needed)
curl -X POST "https://your-proxy-url/reload/anthropic_beta_headers" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Or schedule automatic reloads every 24 hours
curl -X POST "https://your-proxy-url/schedule/anthropic_beta_headers_reload?hours=24" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

This prevents future incidents where Claude Code introduces new headers before LiteLLM configuration is updated.

Configuration format

The anthropic_beta_headers_config.json file maps input headers to provider-specific output headers:

{
  "description": "Mapping of Anthropic beta headers for each provider.",
  "anthropic": {
    "advanced-tool-use-2025-11-20": "advanced-tool-use-2025-11-20",
    "computer-use-2025-01-24": "computer-use-2025-01-24"
  },
  "bedrock_converse": {
    "advanced-tool-use-2025-11-20": null,
    "computer-use-2025-01-24": "computer-use-2025-01-24"
  },
  "azure_ai": {
    "advanced-tool-use-2025-11-20": "advanced-tool-use-2025-11-20",
    "computer-use-2025-01-24": "computer-use-2025-01-24"
  }
}

Validation rules:

1. Headers must exist in the mapping for the target provider
2. Headers with null values are filtered out (unsupported)
3. Header names can be transformed per-provider (e.g., Bedrock uses different names for some features)

Resolution steps for users

For users still experiencing issues, update to the latest LiteLLM version if < v1.81.11-nightly:

pip install --upgrade litellm

Or manually reload the configuration without restarting:

curl -X POST "https://your-proxy-url/reload/anthropic_beta_headers" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Related documentation

• Managing Anthropic Beta Headers - Complete configuration guide
• anthropic_beta_headers_config.json - Current configuration file