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

[elithrar]

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)

[changeset-bot]

🦋 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-actions]

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]

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

[petebacondarwin]

@claude review this

[claude]

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]

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