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

* wrangler: clearer user-facing error for self-signed cert issues
* wrangler: add changeset for this

Author: elithrar

.changeset/cute-cat-club.md

@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+Add helpful warning when SSL certificate errors occur due to corporate proxies or VPNs intercepting HTTPS traffic. When errors like "self-signed certificate in certificate chain" are detected, wrangler now displays guidance about installing missing system roots from your corporate proxy vendor.

packages/wrangler/src/__tests__/core/handle-errors.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { handleError } from "../../core/handle-errors";
+import { mockConsoleMethods } from "../helpers/mock-console";
+
+describe("handleError", () => {
+	const std = mockConsoleMethods();
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe("SSL/TLS certificate errors", () => {
+		it("should log a warning for self-signed certificate errors", async () => {
+			const error = new Error("self-signed certificate in certificate chain");
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+			expect(std.warn).toContain("certificate mismatch");
+			expect(std.warn).toContain("install the missing system roots");
+		});
+
+		it("should log a warning for unable to verify first certificate errors", async () => {
+			const error = new Error("unable to verify the first certificate");
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+		});
+
+		it("should log a warning for unable to get local issuer certificate errors", async () => {
+			const error = new Error("unable to get local issuer certificate");
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+		});
+
+		it("should log a warning when certificate error is in error cause", async () => {
+			const cause = new Error("self-signed certificate in certificate chain");
+			const error = new Error("fetch failed", { cause });
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+		});
+
+		it("should log a warning when certificate error is part of a longer message", async () => {
+			const error = new Error(
+				"Request failed: self-signed certificate in certificate chain (details: some info)"
+			);
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+		});
+
+		it("should not log a warning for unrelated errors", async () => {
+			const error = new Error("Connection refused");
+
+			await handleError(error, {}, []);
+
+			expect(std.warn).not.toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+		});
+
+		it("should still log the original error after the warning", async () => {
+			const error = new Error("self-signed certificate in certificate chain");
+
+			await handleError(error, {}, []);
+
+			// The warning should appear
+			expect(std.warn).toContain(
+				"Wrangler detected that a corporate proxy or VPN might be enabled"
+			);
+			// The original error should also be logged
+			expect(std.err).toContain("self-signed certificate in certificate chain");
+		});
+	});
+});

packages/wrangler/src/core/handle-errors.ts

@@ -27,6 +27,36 @@ import { logPossibleBugMessage } from "../utils/logPossibleBugMessage";
 import type { ReadConfigCommandArgs } from "../config";
 import type { ComplianceConfig } from "@cloudflare/workers-utils";
 
+/**
+ * SSL/TLS certificate error messages that indicate a corporate proxy or VPN
+ * may be intercepting HTTPS traffic with a custom root certificate.
+ */
+const SSL_ERROR_SELF_SIGNED_CERT =
+	"self-signed certificate in certificate chain";
+const SSL_ERROR_UNABLE_TO_VERIFY = "unable to verify the first certificate";
+const SSL_ERROR_UNABLE_TO_GET_ISSUER = "unable to get local issuer certificate";
+
+const SSL_CERT_ERROR_MESSAGES = [
+	SSL_ERROR_SELF_SIGNED_CERT,
+	SSL_ERROR_UNABLE_TO_VERIFY,
+	SSL_ERROR_UNABLE_TO_GET_ISSUER,
+];
+
+/**
+ * Check if an error (or its cause) is related to SSL/TLS certificate validation,
+ * which commonly occurs when a corporate proxy or VPN intercepts HTTPS traffic.
+ */
+function isCertificateError(e: unknown): boolean {
+	const message = e instanceof Error ? e.message : String(e);
+	const causeMessage =
+		e instanceof Error && e.cause instanceof Error ? e.cause.message : "";
+
+	return SSL_CERT_ERROR_MESSAGES.some(
+		(errorText) =>
+			message.includes(errorText) || causeMessage.includes(errorText)
+	);
+}
+
 /**
  * Handles an error thrown during command execution.
  *
@@ -42,6 +72,16 @@ export async function handleError(
 	let loggableException = e;
 
 	logger.log(""); // Just adds a bit of space
+
+	// Log a helpful warning for SSL certificate errors caused by corporate proxies/VPNs
+	if (isCertificateError(e)) {
+		logger.warn(
+			"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."
+		);
+	}
+
 	if (e instanceof CommandLineArgsError) {
 		logger.error(e.message);
 		// We are not able to ask the `wrangler` CLI parser to show help for a subcommand programmatically.