Skip to content
← Back to release · 2.1.309
New features / v2.1.309

[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 connected without the error text. To read it in the logs:
    1. Run Claude Code: Show Logs from the Command Palette to open the Claude VSCode output channel.
    2. Click Reconnect on the tab and wait until it stops showing Connecting….
    3. Search the channel for Error fetching remote sessions: or Failed to fetch organization UUID:, then read the error text after that prefix on the newest matching line.
  • Log warning: a warning naming an authority that Claude Code does not trust reports a certificate error. Behind a TLS-inspecting proxy, set NODE_EXTRA_CA_CERTS in env in ~/.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.json on 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

Change details