ANTHROPIC_CUSTOM_HEADERS
A Claude Code environment variable, read out of the shipped bundle. It has been in the build since v2.1.138, including the newest one read.
Custom headers to add to requests (Name: Value format, newline-separated for multiple headers). If a name or value contains a character an HTTP header can't carry, such as a curly quote or a zero-width space, the request fails with an error that identifies the pair by position. Requires Claude Code v2.1.227 or later. Invalid request header value lists the exact character set and where the check runs. A value that sets a credential, org or tenant, routing, or API-behavior header, such as Authorization or Host, counts as a setting that needs approval when server-managed settings deliver it. From project or local settings, such a value follows the rules for when env values apply
Anthropic's own wording. Read off Environment variables, captured 2026-09-28.
In the changelogs
18Releases whose published page names ANTHROPIC_CUSTOM_HEADERS.
-
v2.1.296
Git commands run by Claude Code no longer inherit GIT_CONFIG
Claude Code clears any
GIT_CONFIGvariable before running git, and now comparesANTHROPIC_CUSTOM_HEADERSwith a value from another sourcefound in this entry's text
-
v2.1.296
Claude Code now gathers extra request headers when it sets up its API connection
When Claude Code sets up its connection to the API, it now fetches extra headers and adds them to every kind of connection it makes
found in this entry's text
-
v2.1.296
Claude Code can send a new header describing the client and its setup
A new
x-claude-code-wiggly-doverequest header can carry client version, permission mode, sandbox and git details, and is off by defaultfound in this entry's text
-
v2.1.287
ANTHROPIC_CUSTOM_HEADERS is read by a shared helper
Claude Code now reads
ANTHROPIC_CUSTOM_HEADERSthrough a single shared function instead of separate inline codefound in this entry's text, named in this entry
-
v2.1.287
Custom Authorization headers read through a shared parser; a self-hosted remote type
An Authorization header set in ANTHROPIC_CUSTOM_HEADERS is now read by a shared parser, and a self_hosted remote environment type is recognised
found in this entry's text, named in this entry
-
v2.1.284
Bedrock and Vertex model-access checks are remembered for 15 minutes
A successful check that your cloud provider gives you access to a model is now saved on disk and reused for 15 minutes
found in this entry's text
-
v2.1.277
A custom-header spread in the API client now includes an inert no-op spread
A no-op false value was added to the API client's custom-header spread, with no apparent effect
found in this entry's text
-
v2.1.267
Org-policy beta-block message reworded
The message shown when an org policy blocks experimental beta headers was reworded
found in this entry's text
-
v2.1.260
API client now sends anthropic-beta custom header value only when a flag is on
A custom anthropic-beta header can be forwarded, but only once a gate is enabled.
found in this entry's text, named in this entry
-
v2.1.260
Org compliance policy can silently drop custom anthropic-beta headers
HIPAA compliance mode now silently drops custom anthropic-beta headers and disables 1M-context.
found in this entry's text, named in this entry
-
v2.1.251
Custom headers from settings are now validated before reaching the environment
Custom headers from settings are validated before entering the environment.
named in this entry, found in this entry's text
-
v2.1.248
Gateway model discovery explains why it skipped, and can use apiKeyHelper
Gateway model discovery can authenticate with apiKeyHelper and logs why it skipped.
found in this entry's text
-
v2.1.227
Bad auth headers reported with their real error code
Bad auth header errors now show the real error code, including keys you set yourself.
found in this entry's text
-
v2.1.227
Auth failures now name the credential source
Auth failures now name where the bad credential came from, like your custom headers.
named in this entry, found in this entry's text
-
v2.1.227
Bad HTTP header values are rejected before the request instead of crashing
Illegal header values from your env or key helper now fail clearly instead of crashing.
named in this entry, found in this entry's text
-
v2.1.227
Auth token and custom header failures now say which value is wrong
Bad auth tokens and custom headers now each get a message naming the exact value to fix.
named in this entry, found in this entry's text
-
v2.1.124
Gateway model discovery for
ANTHROPIC_BASE_URLfound in this entry's text
-
v0.2.40
Security Enhancements
found in this entry's text
First cited
6The earliest release whose published evidence quoted ANTHROPIC_CUSTOM_HEADERS was v2.1.227, 10 Aug 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
Presence across releases
1Build by build
149One row per release since the first build this name was read out of. Absent means the build was read and the name was not in it, never mined means no bundle for that release was ever archived, and a declared type or a default is only ever what that release's own bundle stated.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the environment variable does. All environment variables.