[DOCS] Network configuration mTLS rotation does not mention the v2.1.202 in-place rotation handshake fix
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/network-config
Section/Topic
"mTLS authentication" section, specifically the paragraph that describes how Claude Code re-reads the certificate and key files when settings are re-applied.
Current Documentation
The "mTLS authentication" section on the network configuration page currently says:
Claude Code reads the certificate and key files at startup and re-reads them each time it applies settings, including when settings change during a session. To rotate the certificate and key, replace the files at the same paths.
This paragraph describes the re-read behavior on every settings re-apply as if it were always reliable, and gives operators no indication of what to do if a rotation causes transient TLS handshake failures before v2.1.202.
What's Wrong or Missing?
A. The v2.1.202 mTLS handshake fix is not reflected in the rotation guidance
The v2.1.202 changelog entry states:
Fixed transient mTLS handshake failures when settings were re-applied during an in-place client certificate rotation
The network configuration page is the canonical place where an operator learns how to rotate CLAUDE_CODE_CLIENT_CERT and CLAUDE_CODE_CLIENT_KEY in place (i.e., replace the files at the same paths without restarting Claude Code). The current rotation paragraph never acknowledges that this rotation path could fail with a transient mTLS handshake error before v2.1.202, and never states that v2.1.202 made the in-place rotation path reliable.
B. Operators following the documented procedure could still see handshake errors
Because the docs only describe the re-read behavior, an operator who followed the documented "replace the files at the same paths" procedure before v2.1.202 could hit transient mTLS handshake failures after a settings re-apply, with no guidance in the docs explaining why or pointing at the v2.1.202 fix. After v2.1.202 the in-place rotation is reliable, but the docs still do not say so, so operators cannot tell from the docs whether they need a workaround or whether their installed version already handles it.
C. No version-stamped note for the in-place rotation behavior
The page has version-stamped notes elsewhere (e.g., on the API error retry behavior in the errors page). The mTLS rotation paragraph has none, even though the on-the-wire rotation behavior changed in v2.1.202.
Suggested Improvement
Add a version-stamped note to the rotation paragraph that records the v2.1.202 fix, for example:
Before:
Claude Code reads the certificate and key files at startup and re-reads them each time it applies settings, including when settings change during a session. To rotate the certificate and key, replace the files at the same paths.
After:
Claude Code reads the certificate and key files at startup and re-reads them each time it applies settings, including when settings change during a session. To rotate the certificate and key, replace the files at the same paths. {/ min-version: 2.1.202 /}As of v2.1.202, in-place client certificate rotations are reliable: settings re-apply no longer causes transient mTLS handshake failures while the new certificate and key are being picked up. Earlier versions could briefly fail to connect after an in-place rotation; if you are on an older version, restart Claude Code after rotating to avoid the transient failure.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/network-config | 101 | Rotation paragraph for CLAUDE_CODE_CLIENT_CERT / CLAUDE_CODE_CLIENT_KEY |
| https://code.claude.com/docs/en/monitoring-usage | 101 | OTLP mTLS table that defers to the network-config section for cert handling |
| https://code.claude.com/docs/en/env-vars | 160–162 | CLAUDE_CODE_CLIENT_CERT, CLAUDE_CODE_CLIENT_KEY, CLAUDE_CODE_CLIENT_KEY_PASSPHRASE reference rows |
Total scope: 3 pages reference the rotation behavior, with the primary fix location on the Network configuration page.
Version: v2.1.202 introduced this fix.
The OTEL mTLS env var docs also separately describe a v2.1.169 settings-trust hardening for the same CLAUDE_CODE_CLIENT_CERT / CLAUDE_CODE_CLIENT_KEY env vars; that is a different root cause (untrusted project settings) from this v2.1.202 fix (transient handshake after in-place rotation).