utils: surface troubleshooting guidance for certificate trust errors#2357
Open
alexweininger wants to merge 5 commits into
Open
utils: surface troubleshooting guidance for certificate trust errors#2357alexweininger wants to merge 5 commits into
alexweininger wants to merge 5 commits into
Conversation
Operations that fail because the Node extension host cannot build a trusted TLS certificate chain (for example "unable to get local issuer certificate") currently show only the raw, cryptic error. On developer machines this is almost always a corporate proxy or SSL-inspection appliance whose root CA is not trusted by Node, and the fix is documented (NODE_EXTRA_CA_CERTS), but the error gives no hint. Add a shared classifier isCertificateTrustError() and wire it into the central handleError path in callWithTelemetryAndErrorHandling, so every extension that uses it automatically gets: a short explanatory hint appended to the notification and output channel, plus a "Learn more" button that opens the troubleshooting docs. Classification is limited to known Node/OpenSSL certificate error codes and their human-readable messages to avoid false positives on unrelated network errors. Related to microsoft/vscode-azureappservice#2899 Related to microsoft/vscode-azurefunctions#5124 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the shared @microsoft/vscode-azext-utils error-handling path by detecting TLS certificate trust-chain failures and surfacing actionable troubleshooting guidance (hint text + output channel details + “Learn more” link) for extensions using callWithTelemetryAndErrorHandling.
Changes:
- Added
isCertificateTrustError(parsedError)and a canonical troubleshooting URL constant for certificate trust failures. - Integrated certificate-trust detection into
handleErrorto append guidance to notifications/output and provide a “Learn more” button. - Added unit tests covering common Node/OpenSSL certificate-chain error codes and message fragments.
Show a summary per file
| File | Description |
|---|---|
| utils/test/certificateTrustError.test.ts | Adds unit tests validating the certificate trust error classifier behavior. |
| utils/src/utils/certificateTrustError.ts | Introduces the certificate trust error classifier and troubleshooting link constant. |
| utils/src/callWithTelemetryAndErrorHandling.ts | Wires the classifier into central error handling to show guidance and a “Learn more” button. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 3/3 changed files
- Comments generated: 2
- Review effort level: Low
|
|
||
| if (!context.errorHandling.suppressDisplay) { | ||
| const isCertError: boolean = isCertificateTrustError(unMaskedErrorData); | ||
| const certHint: string = l10n.t('This can happen behind a corporate proxy or SSL-inspection appliance whose certificate authority is not trusted by VS Code. See the troubleshooting steps for how to trust it.'); |
Member
Author
There was a problem hiding this comment.
Agreed, reworded in 8a109f4 to attribute the failure to the Node.js extension host being unable to build a trusted chain (rather than 'VS Code'), and to mention NODE_EXTRA_CA_CERTS.
Fixes CI lint failure (@typescript-eslint/no-unnecessary-type-assertion): the object literal already satisfies IParsedError, so the cast is redundant. Build the base as a typed const and spread instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove 'certificate has expired' from the classifier: an expired leaf/server cert (or bad local clock) is not an untrusted corporate root CA, so including it risks false positives that surface proxy/CA guidance when it does not apply. - Reword the hint to attribute the failure to the Node.js extension host being unable to build a trusted chain (not 'VS Code'), and mention NODE_EXTRA_CA_CERTS. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Completeness: also match the non-_LOCALLY issuer-cert error code and its human-readable message, which some OpenSSL/Node versions surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
alexweininger
commented
Jul 1, 2026
| * Default troubleshooting documentation for certificate trust failures. All Azure extensions | ||
| * link their README troubleshooting sections to this canonical location. | ||
| */ | ||
| export const certificateTroubleshootingLink: string = 'https://github.com/microsoft/vscode-azureresourcegroups/blob/main/README.md#troubleshooting'; |
Member
Author
There was a problem hiding this comment.
turn this into aka.ms link
Member
Author
There was a problem hiding this comment.
here's the aka.ms link I created: aka.ms/AA11ri61
Member
Author
There was a problem hiding this comment.
Done in 6cec7b3 — certificateTroubleshootingLink now points at https://aka.ms/AA11ri61 instead of the branch-specific README URL, so it survives README moves/renames. Updated the doc comment to match.
Point certificateTroubleshootingLink at the stable aka.ms/AA11ri61 redirect instead of a branch-specific GitHub README URL, so it survives README moves. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
bwateratmsft
approved these changes
Jul 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When an operation fails because the Node.js extension host cannot build a trusted TLS certificate chain (for example
unable to get local issuer certificate/SELF_SIGNED_CERT_IN_CHAIN), the extension shows only the raw OpenSSL error. On developer machines this is almost always a corporate proxy or SSL-inspection appliance whose root CA is not trusted by Node. The fix is documented (NODE_EXTRA_CA_CERTS), but the error itself gives the user no hint that this is the cause or where to look.Related to microsoft/vscode-azureappservice#2899 and microsoft/vscode-azurefunctions#5124.
Change
isCertificateTrustError(parsedError)(utils/src/utils/certificateTrustError.ts) that recognizes the known Node/OpenSSL certificate-chain error codes and their human-readable messages.handleErrorpath incallWithTelemetryAndErrorHandling. When an error is classified as a certificate trust failure and display is not suppressed, the extension now:Because this lives in the shared
@microsoft/vscode-azext-utilserror path, every extension that usescallWithTelemetryAndErrorHandlinggets the improved guidance automatically, with no per-extension changes.Scope / design notes
index.d.tsis untouched.Validation
tsc -p ./ --noEmitclean,eslint --max-warnings 0clean.vscode-test: 249 passing, including 5 new tests for the classifier.