[VSCode] Warn on certificate verification failures
CHANGELOG · original
[VSCode] Added a log warning that says what to do when dictation or the extension's own requests fail certificate verification, such as behind a TLS-inspecting proxy Open official changelog ↗ Documentation
Documentation excerpt
Dictation or the Web tab fails behind a TLS-inspecting proxy
When dictation or the Web tab fails with a certificate error such as unable to get local issuer certificate, set NODE_EXTRA_CA_CERTS in the env block of ~/.claude/settings.json. Set it to the path of a PEM file with your proxy's root CA certificate, which your IT team can give you. The failure appears on the microphone button or Web tab, or in the logs:
- Dictation: the microphone button shows the error text after
Dictation error: WebSocket error:. - Web tab: the tab that lists cloud sessions shows
Remote server is not connectedwithout the error text. To read it in the logs:- Run Claude Code: Show Logs from the Command Palette to open the
Claude VSCodeoutput channel. - Click Reconnect on the tab and wait until it stops showing
Connecting…. - Search the channel for
Error fetching remote sessions:orFailed to fetch organization UUID:, then read the error text after that prefix on the newest matching line.
- Run Claude Code: Show Logs from the Command Palette to open the
- Log warning: a warning naming
an authority that Claude Code does not trustreports a certificate error. Behind a TLS-inspecting proxy, setNODE_EXTRA_CA_CERTSinenvin~/.claude/settings.json. Versions before v2.1.309 don't log this warning.
This fix requires extension version 2.1.307 or later, so update the extension first. Then set NODE_EXTRA_CA_CERTS to the certificate file's full path, written without ~. For a Windows path, write each backslash twice in settings.json, as in C:\\certs\\example-ca.pem.
[!NOTE]
In a window connected to WSL, an SSH host, a dev container, or another system, save the certificate file and edit
~/.claude/settings.jsonon that system, not on your local computer.
This example names a certificate file at the Linux or macOS path /etc/ssl/certs/example-ca.pem:
{
"env": {
"NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
}
}
Save settings.json, then start a recording or click Reconnect again. If the error comes back, open the output channel with Claude Code: Show Logs and search it for use the CA certificates file. Such a warning gives the reason the extension can't use your file and says where it read the path. Then find each place you set NODE_EXTRA_CA_CERTS in this table and do what its row says:
| Where you set it | What to do |
|---|---|
| The environment VS Code was started with | A value set here takes precedence over one in ~/.claude/settings.json, even when the file it names can't be used. Correct or remove it, then restart VS Code |
env in ~/.claude/settings.json |
Correct the value or the file it names, then start a recording or click Reconnect again |
VS Code's claudeCode.environmentVariables setting, ~/.claude.json, a project's .claude/settings.json or .claude/settings.local.json, or managed settings |
A value set here doesn't apply to dictation or the Web tab. Set the variable in env in ~/.claude/settings.json as well |
Documentation snapshot · 2026-11-20