From 6bad149aabf4315183c6657ba9802a40f4494aff Mon Sep 17 00:00:00 2001
From: Sameer Kankute <sameer@berri.ai>
Date: Fri, 6 Feb 2026 17:54:56 +0530
Subject: [PATCH] Add documentation related to new beta header json

---
 .../tutorials/claude_code_beta_headers.md     | 129 ++++++++++++++++++
 docs/my-website/sidebars.js                   |   1 +
 litellm/anthropic_beta_headers_config.json    |   3 +-
 3 files changed, 131 insertions(+), 2 deletions(-)
 create mode 100644 docs/my-website/docs/tutorials/claude_code_beta_headers.md

diff --git a/docs/my-website/docs/tutorials/claude_code_beta_headers.md b/docs/my-website/docs/tutorials/claude_code_beta_headers.md
new file mode 100644
index 00000000000..9c1645e0277
--- /dev/null
+++ b/docs/my-website/docs/tutorials/claude_code_beta_headers.md
@@ -0,0 +1,129 @@
+import Image from '@theme/IdealImage';
+
+# Claude Code - Fixing Invalid Beta Header Errors
+
+When using Claude Code with LiteLLM and non-Anthropic providers (Bedrock, Azure AI, Vertex AI), you may encounter "invalid beta header" errors. This guide explains how to fix these errors locally or contribute a fix to LiteLLM.
+
+## What Are Beta Headers?
+
+Anthropic uses beta headers to enable experimental features in Claude. When you use Claude Code, it may send beta 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. When an unsupported beta header is sent to a provider, you'll see an error.
+
+## Common Error Message
+
+```bash
+Error: The model returned the following errors: invalid beta flag
+```
+
+## How LiteLLM Handles Beta Headers
+
+LiteLLM automatically filters out unsupported beta headers using a configuration file:
+
+```
+litellm/litellm/anthropic_beta_headers_config.json
+```
+
+This JSON file lists which beta headers are **unsupported** for each provider. Headers not in the unsupported list are passed through to the provider.
+
+## Quick Fix: Update Config Locally
+
+If you encounter an invalid beta header error, you can fix it immediately by updating the config file locally.
+
+### Step 1: Locate the Config File
+
+Find the file in your LiteLLM installation:
+
+```bash
+# If installed via pip
+cd $(python -c "import litellm; import os; print(os.path.dirname(litellm.__file__))")
+
+# The config file is at:
+# litellm/anthropic_beta_headers_config.json
+```
+
+### Step 2: Add the Unsupported Header
+
+Open `anthropic_beta_headers_config.json` and add the problematic header to the appropriate provider's list:
+
+```json title="anthropic_beta_headers_config.json"
+{
+  "description": "Unsupported Anthropic beta headers for each provider. Headers listed here will be dropped. Headers not listed are passed through as-is.",
+  "anthropic": [],
+  "azure_ai": [],
+  "bedrock_converse": [
+    "prompt-caching-scope-2026-01-05",
+    "bash_20250124",
+    "bash_20241022",
+    "text_editor_20250124",
+    "text_editor_20241022",
+    "compact-2026-01-12",
+    "advanced-tool-use-2025-11-20",
+    "web-fetch-2025-09-10",
+    "code-execution-2025-08-25",
+    "skills-2025-10-02",
+    "files-api-2025-04-14"
+  ],
+  "bedrock": [
+    "advanced-tool-use-2025-11-20",
+    "prompt-caching-scope-2026-01-05",
+    "structured-outputs-2025-11-13",
+    "web-fetch-2025-09-10",
+    "code-execution-2025-08-25",
+    "skills-2025-10-02",
+    "files-api-2025-04-14"
+  ],
+  "vertex_ai": [
+    "prompt-caching-scope-2026-01-05"
+  ]
+}
+```
+
+### Step 3: Restart Your Application
+
+After updating the config file, restart your LiteLLM proxy or application:
+
+```bash
+# If using LiteLLM proxy
+litellm --config config.yaml
+
+# If using Python SDK
+# Just restart your Python application
+```
+
+The updated configuration will be loaded automatically.
+
+## Contributing a Fix to LiteLLM
+
+Help the community by contributing your fix! If your local changes work, please raise a PR with the addition of the header and we will merge it.
+
+
+## How Beta Header Filtering Works
+
+When you make a request through LiteLLM:
+
+```mermaid
+sequenceDiagram
+    participant CC as Claude Code
+    participant LP as LiteLLM
+    participant Config as Beta Headers Config
+    participant Provider as Provider (Bedrock/Azure/etc)
+
+    CC->>LP: Request with beta headers
+    Note over CC,LP: anthropic-beta: header1,header2,header3
+    
+    LP->>Config: Load unsupported headers for provider
+    Config-->>LP: Returns unsupported list
+    
+    Note over LP: Filter headers:<br/>- Remove unsupported<br/>- Keep supported
+    
+    LP->>Provider: Request with filtered headers
+    Note over LP,Provider: anthropic-beta: header2<br/>(header1, header3 removed)
+    
+    Provider-->>LP: Success response
+    LP-->>CC: Response
+```
\ No newline at end of file
diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js
index 85573599e44..c5ec7a2aaf1 100644
--- a/docs/my-website/sidebars.js
+++ b/docs/my-website/sidebars.js
@@ -128,6 +128,7 @@ const sidebars = {
             "tutorials/claude_mcp",
             "tutorials/claude_non_anthropic_models",
             "tutorials/claude_code_plugin_marketplace",
+            "tutorials/claude_code_beta_headers",
           ]
         },
         "tutorials/opencode_integration",
diff --git a/litellm/anthropic_beta_headers_config.json b/litellm/anthropic_beta_headers_config.json
index b6b0753f9ba..193091c0176 100644
--- a/litellm/anthropic_beta_headers_config.json
+++ b/litellm/anthropic_beta_headers_config.json
@@ -22,8 +22,7 @@
     "web-fetch-2025-09-10",
     "code-execution-2025-08-25",
     "skills-2025-10-02",
-    "files-api-2025-04-14",
-    "code-execution-2025-08-25"
+    "files-api-2025-04-14"
   ],
   "vertex_ai": [
     "prompt-caching-scope-2026-01-05"