Thanks to visit codestin.com
Credit goes to github.com

Skip to content

wrangler: clearer user-facing error for self-signed cert issues #11615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
elithrar merged 2 commits into from
Dec 11, 2025
Merged

wrangler: clearer user-facing error for self-signed cert issues #11615

elithrar merged 2 commits into from
Dec 11, 2025

Conversation

@elithrar
Copy link
Contributor

@elithrar elithrar commented Dec 11, 2025 •
edited
Loading

This PR adds a more useful, actionable error message when wrangler runs into self-signed certificate issues. Right now, the "self-signed" (and related) error emitted from Node.js is unclear to users who are just using a computer and not TLS/SSL/system root aware experts.

Generated via opencode with the following initial prompt (and minimal additional changes):

When a user has a corporate VPN or proxy on their system, attempts by wrangler (incl. its Node.js internals) to make HTTP requests fail certificate validate until a user installs/updates their system roots based on whatever VPN/SASE/ZT vendor they use.

Right now, we emit a generic, inactionable "[cause]: Error: self-signed certificate in certificate chain" error in these cases, which does not tell the user where to go.

I want you to look at how we can catch errors that match "self-signed certificate in certificate chain" from any API/fetch calls wrangler makes, and instead return:

- The original error as-is
- A helpful warning in addition with the text: "wrangler detected that a corporate proxy or VPN might be enabled on your machine, resulting in API calls failing due to a certificate mismatch. It is likely that you need to install the missing system roots provided by your corporate proxy vendor."

Show me where you intend to make these changes.

cc @fisherdarling :-)

  • Tests
    • Tests included/updated
    • Tests not necessary because:
  • Public documentation
    • Cloudflare docs PR(s):
    • Documentation not necessary because: this is a change to error messaging only.
  • Wrangler V3 Backport
    • [] Wrangler PR: TBD (conflicts require manual creation)
    • Not necessary because: this is a change to error messaging only.

A picture of a cute animal (not mandatory, but encouraged)

maebe_yawn

@elithrar elithrar requested a review from a team as a code owner December 11, 2025 14:57
@changeset-bot
Copy link

changeset-bot bot commented Dec 11, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: 29d6fd9

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-project-automation github-project-automation bot moved this to Untriaged in workers-sdk Dec 11, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Dec 11, 2025

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main self-signed-cert-warning might be a good starting point.

Notes:

  • your PR branch should be named v3-backport-11615
  • add the skip-v3-pr label to the current PR to stop this workflow from failing

petebacondarwin
petebacondarwin approved these changes Dec 11, 2025
View reviewed changes
Copy link
Contributor

@petebacondarwin petebacondarwin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good but I do think this should be back ported.

@github-project-automation github-project-automation bot moved this from Untriaged to Approved in workers-sdk Dec 11, 2025
@petebacondarwin petebacondarwin force-pushed the self-signed-cert-warning branch from dbacc2b to 29d6fd9 Compare December 11, 2025 15:15
@petebacondarwin
Copy link
Contributor

petebacondarwin commented Dec 11, 2025

@claude review this

@claude
Copy link
Contributor

claude bot commented Dec 11, 2025 •
edited
Loading

Claude finished @petebacondarwin's task —— View job

Code Review Complete ✅

Todo List:

  • Read and analyze the changeset file
  • Review the new test file for comprehensive coverage
  • Examine the core error handling implementation
  • Check for potential issues and improvements
  • Provide comprehensive review feedback

Review Feedback

This is a solid implementation that addresses a real user pain point. The code is well-structured, thoroughly tested, and follows good practices.

✅ Strengths

Clear Problem Definition: The SSL certificate error messages are well-documented with descriptive constants (packages/wrangler/src/core/handle-errors.ts:34-43).

Comprehensive Error Detection: The isCertificateError() function (packages/wrangler/src/core/handle-errors.ts:49-58) properly checks both the main error message and the cause property, covering various error propagation scenarios.

Excellent Test Coverage: The test suite (packages/wrangler/src/__tests__/core/handle-errors.test.ts) covers all the key scenarios:

  • Direct certificate error messages (lines 13-43)
  • Error chains with cause property (lines 45-54)
  • Partial string matches (lines 56-66)
  • Negative cases to prevent false positives (lines 68-76)
  • Verification that original errors are still logged (lines 78-89)

User-Friendly Messaging: The warning text is clear, actionable, and explains both the problem and solution without being overly technical.

Non-Invasive Implementation: The warning is added without disrupting existing error handling flow - original errors are still logged normally.

🔍 Minor Observations

Consistent Placement: The certificate error check is logically placed early in the error handling flow (packages/wrangler/src/core/handle-errors.ts:77-83), which ensures users see the helpful guidance before the technical error details.

String Matching Approach: Using includes() for error detection is pragmatic here since these are well-established Node.js SSL error messages that are unlikely to change.

📝 Changeset Quality

The changeset properly categorizes this as a patch change and provides a clear, user-focused description that will be helpful in release notes.

Overall Assessment: This PR effectively solves a common user experience problem with minimal risk and good engineering practices. The implementation is ready for merge.

@elithrar
Copy link
Contributor Author

elithrar commented Dec 11, 2025

@petebacondarwin I'm glad Claude liked it because Claude (Opus 4.5) wrote it 😉

@elithrar elithrar merged commit ed42010 into main Dec 11, 2025
27 of 33 checks passed
@elithrar elithrar deleted the self-signed-cert-warning branch December 11, 2025 16:29
@github-project-automation github-project-automation bot moved this from Approved to Done in workers-sdk Dec 11, 2025
@workers-devprod workers-devprod mentioned this pull request Dec 11, 2025
Merged
dario-piotrowicz pushed a commit that referenced this pull request Dec 11, 2025
@elithrar @dario-piotrowicz
wrangler: clearer user-facing error for self-signed cert issues (#11615)
d1bc965 
* wrangler: clearer user-facing error for self-signed cert issues
* wrangler: add changeset for this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@petebacondarwin petebacondarwin petebacondarwin approved these changes

+1 more reviewer

@fisherdarling fisherdarling fisherdarling approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

workers-sdk
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@elithrar @petebacondarwin @fisherdarling