[wrangler] Improve error message when port binding is blocked by sandbox (#12556)

Author: ascorbic

.changeset/fix-getport-host-mismatch.md

@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+Fix port availability check probing the wrong host when host changes
+
+`memoizeGetPort` correctly invalidated its cached port when called with a different host, but then still probed the original host for port availability. This could return a port that was free on the original host but already in use on the requested one, leading to bind failures at startup.

.changeset/sandbox-eperm-bind-error.md

@@ -0,0 +1,7 @@
+---
+"wrangler": patch
+---
+
+Improve error message when port binding is blocked by a sandbox or security policy
+
+When running `wrangler dev` inside a restricted environment (such as an AI coding agent sandbox or locked-down container), the port availability check would fail with a raw `EPERM` error. This now provides a clear message explaining that a sandbox or security policy is blocking network access, rather than the generic permission error that previously pointed at the file system.

packages/wrangler/src/__tests__/utils-memoizeGetPort.test.ts

@@ -0,0 +1,85 @@
+import { UserError } from "@cloudflare/workers-utils";
+import getPort from "get-port";
+import { describe, it, vi } from "vitest";
+import { memoizeGetPort } from "../utils/memoizeGetPort";
+
+vi.mock("get-port", () => {
+	return {
+		default: vi.fn().mockResolvedValue(8787),
+		portNumbers: (from: number, to: number) => [from, to],
+	};
+});
+
+const mockGetPort = vi.mocked(getPort);
+
+describe("memoizeGetPort()", () => {
+	it("should throw a UserError when port binding is blocked by EPERM", async ({
+		expect,
+	}) => {
+		mockGetPort.mockImplementationOnce(() => {
+			throw Object.assign(
+				new Error("listen EPERM: operation not permitted ::1:8787"),
+				{ code: "EPERM", syscall: "listen" }
+			);
+		});
+
+		const getPortFn = memoizeGetPort(8787, "localhost");
+		await expect(getPortFn()).rejects.toThrow(UserError);
+	});
+
+	it("should mention sandbox in EPERM error message", async ({ expect }) => {
+		mockGetPort.mockImplementationOnce(() => {
+			throw Object.assign(
+				new Error("listen EPERM: operation not permitted ::1:8787"),
+				{ code: "EPERM", syscall: "listen" }
+			);
+		});
+
+		const getPortFn = memoizeGetPort(8787, "localhost");
+		await expect(getPortFn()).rejects.toThrow(/sandbox or security policy/);
+	});
+
+	it("should throw a UserError when port binding is blocked by EACCES", async ({
+		expect,
+	}) => {
+		const eaccesError = Object.assign(
+			new Error("listen EACCES: permission denied 127.0.0.1:8787"),
+			{ code: "EACCES", syscall: "listen" }
+		);
+		mockGetPort.mockImplementation(() => {
+			throw eaccesError;
+		});
+
+		const getPortFn = memoizeGetPort(8787, "127.0.0.1");
+		await expect(getPortFn()).rejects.toThrow(UserError);
+		await expect(getPortFn()).rejects.toThrow(/sandbox or security policy/);
+
+		mockGetPort.mockReset();
+	});
+
+	it("should re-throw non-permission errors unchanged", async ({ expect }) => {
+		mockGetPort.mockImplementation(() => {
+			throw new Error("something else went wrong");
+		});
+
+		const getPortFn = memoizeGetPort(8787, "localhost");
+		await expect(getPortFn()).rejects.toThrow("something else went wrong");
+		await expect(getPortFn()).rejects.not.toThrow(UserError);
+
+		mockGetPort.mockReset();
+	});
+
+	it("should not treat filesystem EPERM as a network bind error", async ({
+		expect,
+	}) => {
+		mockGetPort.mockImplementationOnce(() => {
+			throw Object.assign(
+				new Error("EPERM: operation not permitted, open '/tmp/foo'"),
+				{ code: "EPERM", syscall: "open" }
+			);
+		});
+
+		const getPortFn = memoizeGetPort(8787, "localhost");
+		await expect(getPortFn()).rejects.not.toThrow(UserError);
+	});
+});

packages/wrangler/src/utils/memoizeGetPort.ts

@@ -1,10 +1,22 @@
+import { UserError } from "@cloudflare/workers-utils";
 import ci from "ci-info";
 import getPort, { portNumbers } from "get-port";
 
 // Probe consecutive ports to increase the chance to get the same port across dev sessions.
 // In CI, we avoid probing consecutive ports to reduce the chance of collisions
 const NUM_CONSECUTIVE_PORTS_TO_PROBE = ci.isCI ? 0 : 10;
 
+function isNetworkBindPermissionError(e: unknown): boolean {
+	return (
+		e !== null &&
+		typeof e === "object" &&
+		"code" in e &&
+		(e.code === "EPERM" || e.code === "EACCES") &&
+		"syscall" in e &&
+		(e.syscall === "listen" || e.syscall === "bind")
+	);
+}
+
 /**
  * Get an available TCP port number.
  *
@@ -13,26 +25,38 @@ const NUM_CONSECUTIVE_PORTS_TO_PROBE = ci.isCI ? 0 : 10;
  * - Avoiding calling `getPort()` multiple times by memoizing the first result.
  *
  * @param defaultPort The preferred port to use when available
- * @param host The host to probe for available ports
+ * @param defaultHost The default host to probe for available ports (can be overridden per-call)
  */
-export function memoizeGetPort(defaultPort: number, host: string) {
+export function memoizeGetPort(defaultPort: number, defaultHost: string) {
 	let portValue: number | undefined;
-	let cachedHost = host;
-	return async (forHost: string = host) => {
+	let cachedHost = defaultHost;
+	return async (forHost: string = defaultHost) => {
 		if (forHost !== cachedHost) {
 			portValue = undefined;
 			cachedHost = forHost;
 		}
-		// Check a specific host to avoid probing all local addresses.
-		portValue =
-			portValue ??
-			(await getPort({
-				port: portNumbers(
-					defaultPort,
-					defaultPort + NUM_CONSECUTIVE_PORTS_TO_PROBE
-				),
-				host,
-			}));
-		return portValue;
+		try {
+			// Check a specific host to avoid probing all local addresses.
+			portValue =
+				portValue ??
+				(await getPort({
+					port: portNumbers(
+						defaultPort,
+						defaultPort + NUM_CONSECUTIVE_PORTS_TO_PROBE
+					),
+					host: forHost,
+				}));
+			return portValue;
+		} catch (e) {
+			if (isNetworkBindPermissionError(e)) {
+				throw new UserError(
+					`Failed to bind to ${forHost}:${defaultPort}: permission denied.\n` +
+						`This usually means a sandbox or security policy is preventing network access.\n` +
+						`If you are running inside a restricted environment (container, VM, AI coding agent, etc.),\n` +
+						`configure it to allow binding to loopback addresses.`
+				);
+			}
+			throw e;
+		}
 	};
 }