Mark more errors as UserError (#10769)

penalosa · web-flow · commit 0a554f9323bb · 2025-09-29T13:40:52.000+01:00
* Mark all containers-shared errors as UserErrors

* D1 &amp; Miniflare

* fix lint

* Update changeset to clarify UserError usage

Clarify the purpose of marking errors as UserError.

* fix lint

* properly handle abort signals
diff --git a/.changeset/popular-moons-knock.md b/.changeset/popular-moons-knock.md
@@ -0,0 +1,7 @@
+---
+"@cloudflare/containers-shared": patch
+"miniflare": patch
+"wrangler": patch
+---
+
+Mark more errors as `UserError` to disable Sentry reporting
diff --git a/fixtures/ratelimit-app/tsconfig.json b/fixtures/ratelimit-app/tsconfig.json
@@ -1,9 +1,9 @@
 {
 	"compilerOptions": {
-		"target": "ES2020",
+		"target": "esnext",
 		"esModuleInterop": true,
 		"module": "CommonJS",
-		"lib": ["ES2020"],
+		"lib": ["esnext"],
 		"types": ["node"],
 		"skipLibCheck": true,
 		"moduleResolution": "node",
diff --git a/fixtures/worker-ts/wrangler.jsonc b/fixtures/worker-ts/wrangler.jsonc
@@ -1,11 +1,6 @@
 {
+	"$schema": "node_modules/wrangler/config-schema.json",
 	"name": "worker-ts",
 	"main": "src/index.ts",
 	"compatibility_date": "2023-05-04",
-	"hyperdrive": [
-		{
-			"binding": "H",
-			"id": "hello",
-		},
-	],
 }
diff --git a/packages/containers-shared/src/build.ts b/packages/containers-shared/src/build.ts
@@ -1,5 +1,6 @@
 import { spawn } from "child_process";
 import { readFileSync } from "fs";
+import { UserError } from "./error";
 import type {
 	BuildArgs,
 	ContainerDevOptions,
@@ -70,7 +71,7 @@ export function dockerBuild(
 			resolve();
 		} else if (!errorHandled) {
 			errorHandled = true;
-			reject(new Error(`Docker build exited with code: ${code}`));
+			reject(new UserError(`Docker build exited with code: ${code}`));
 		}
 	});
 	child.on("error", (err) => {
diff --git a/packages/containers-shared/src/error.ts b/packages/containers-shared/src/error.ts
@@ -0,0 +1,33 @@
+/**
+ * This is used to provide telemetry with a sanitised error
+ * message that could not have any user-identifying information.
+ * Set to `true` to duplicate `message`.
+ *  */
+type TelemetryMessage = {
+	telemetryMessage?: string | true;
+};
+
+/**
+ * Base class for errors where the user has done something wrong. These are not
+ * reported to Sentry. API errors are intentionally *not* `UserError`s, and are
+ * reported to Sentry. This will help us understand which API errors need better
+ * messaging.
+ */
+export class UserError extends Error {
+	telemetryMessage: string | undefined;
+	constructor(
+		message?: string | undefined,
+		options?:
+			| ({
+					cause?: unknown;
+			  } & TelemetryMessage)
+			| undefined
+	) {
+		super(message, options);
+		// Restore prototype chain:
+		// https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-newtarget
+		Object.setPrototypeOf(this, new.target.prototype);
+		this.telemetryMessage =
+			options?.telemetryMessage === true ? message : options?.telemetryMessage;
+	}
+}
diff --git a/packages/containers-shared/src/images.ts b/packages/containers-shared/src/images.ts
@@ -1,4 +1,5 @@
 import { buildImage } from "./build";
+import { UserError } from "./error";
 import {
 	getCloudflareContainerRegistry,
 	isCloudflareRegistryLink,
@@ -73,7 +74,7 @@ export async function prepareContainerImagesForDev(args: {
 	} = args;
 	let aborted = false;
 	if (process.platform === "win32") {
-		throw new Error(
+		throw new UserError(
 			"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container part of your application."
 		);
 	}
@@ -95,7 +96,7 @@ export async function prepareContainerImagesForDev(args: {
 			});
 		} else {
 			if (!isCloudflareRegistryLink(options.image_uri)) {
-				throw new Error(
+				throw new UserError(
 					`Image "${options.image_uri}" is a registry link but does not point to the Cloudflare container registry.\n` +
 						`To use an existing image from another repository, see https://developers.cloudflare.com/containers/image-management/#using-existing-images`
 				);
diff --git a/packages/containers-shared/src/inspect.ts b/packages/containers-shared/src/inspect.ts
@@ -1,4 +1,5 @@
 import { spawn } from "child_process";
+import { UserError } from "./error";
 
 export async function dockerImageInspect(
 	dockerPath: string,
@@ -22,7 +23,7 @@ export async function dockerImageInspect(
 		proc.on("close", (code) => {
 			if (code !== 0) {
 				return reject(
-					new Error(`failed inspecting image locally: ${stderr.trim()}`)
+					new UserError(`failed inspecting image locally: ${stderr.trim()}`)
 				);
 			}
 			resolve(stdout.trim());
diff --git a/packages/containers-shared/src/login.ts b/packages/containers-shared/src/login.ts
@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { ImageRegistriesService, ImageRegistryPermissions } from "./client";
+import { UserError } from "./error";
 import { getCloudflareContainerRegistry } from "./knobs";
 
 /**
@@ -44,7 +45,7 @@ export async function dockerLoginManagedRegistry(pathToDocker: string) {
 			if (code === 0) {
 				resolve();
 			} else {
-				reject(new Error(`Login failed with code: ${code}`));
+				reject(new UserError(`Login failed with code: ${code}`));
 			}
 		});
 	});
diff --git a/packages/containers-shared/src/utils.ts b/packages/containers-shared/src/utils.ts
@@ -2,6 +2,7 @@ import { execFileSync, spawn } from "child_process";
 import { randomUUID } from "crypto";
 import { existsSync, statSync } from "fs";
 import path from "path";
+import { UserError } from "./error";
 import { dockerImageInspect } from "./inspect";
 import type { ContainerDevOptions } from "./types";
 import type { StdioOptions } from "child_process";
@@ -38,13 +39,13 @@ export const runDockerCmd = (
 			resolve({ aborted });
 		} else if (!errorHandled) {
 			errorHandled = true;
-			reject(new Error(`Docker command exited with code: ${code}`));
+			reject(new UserError(`Docker command exited with code: ${code}`));
 		}
 	});
 	child.on("error", (err) => {
 		if (!errorHandled) {
 			errorHandled = true;
-			reject(new Error(`Docker command failed: ${err.message}`));
+			reject(new UserError(`Docker command failed: ${err.message}`));
 		}
 	});
 	return {
@@ -66,7 +67,7 @@ export const runDockerCmdWithOutput = (dockerPath: string, args: string[]) => {
 		const stdout = execFileSync(dockerPath, args, { encoding: "utf8" });
 		return stdout.trim();
 	} catch (error) {
-		throw new Error(
+		throw new UserError(
 			`Failed running docker command: ${(error as Error).message}. Command: ${dockerPath} ${args.join(" ")}`
 		);
 	}
@@ -81,7 +82,7 @@ export const verifyDockerInstalled = async (
 		await runDockerCmd(dockerPath, ["info"], ["inherit", "pipe", "pipe"]);
 	} catch {
 		// We assume this command is unlikely to fail for reasons other than the Docker daemon not running, or the Docker CLI not being installed or in the PATH.
-		throw new Error(
+		throw new UserError(
 			`The Docker CLI could not be launched. Please ensure that the Docker CLI is installed and the daemon is running.\n` +
 				`Other container tooling that is compatible with the Docker CLI and engine may work, but is not yet guaranteed to do so. You can specify an executable with the environment variable WRANGLER_DOCKER_BIN and a socket with DOCKER_HOST.` +
 				`${isDev ? "\nTo suppress this error if you do not intend on triggering any container instances, set dev.enable_containers to false in your Wrangler config or passing in --enable-containers=false." : ""}`
@@ -103,7 +104,7 @@ export const isDockerfile = (
 	const maybeDockerfile = path.resolve(baseDir, image);
 	if (existsSync(maybeDockerfile)) {
 		if (isDir(maybeDockerfile)) {
-			throw new Error(
+			throw new UserError(
 				`${image} is a directory, you should specify a path to the Dockerfile`
 			);
 		}
@@ -116,22 +117,22 @@ export const isDockerfile = (
 		new URL(`https://${image}`);
 	} catch (e) {
 		if (e instanceof Error) {
-			throw new Error(errorPrefix + e.message);
+			throw new UserError(errorPrefix + e.message);
 		}
 		throw e;
 	}
 	const imageParts = image.split("/");
 
 	if (!imageParts[imageParts.length - 1]?.includes(":")) {
-		throw new Error(
+		throw new UserError(
 			errorPrefix +
 				`If this is an image registry path, it needs to include at least a tag ':' (e.g: docker.io/httpd:1)`
 		);
 	}
 
 	// validate URL
 	if (image.includes("://")) {
-		throw new Error(
+		throw new UserError(
 			errorPrefix +
 				`Image reference should not include the protocol part (e.g: docker.io/httpd:1, not https://docker.io/httpd:1)`
 		);
@@ -218,7 +219,7 @@ export async function checkExposedPorts(
 		formatString: "{{ len .Config.ExposedPorts }}",
 	});
 	if (output === "0") {
-		throw new Error(
+		throw new UserError(
 			`The container "${options.class_name}" does not expose any ports. In your Dockerfile, please expose any ports you intend to connect to.\n` +
 				"For additional information please see: https://developers.cloudflare.com/containers/local-dev/#exposing-ports.\n"
 		);
diff --git a/packages/containers-shared/tests/docker-context.test.ts b/packages/containers-shared/tests/docker-context.test.ts
@@ -1,5 +1,6 @@
 import { execFileSync } from "child_process";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { UserError } from "../src/error";
 import { resolveDockerHost } from "../src/utils";
 
 vi.mock("node:child_process");
@@ -41,7 +42,7 @@ describe.skipIf(process.platform !== "linux" && process.env.CI === "true")(
 
 		it("should fall back to platform default when context fails", () => {
 			vi.mocked(execFileSync).mockImplementation(() => {
-				throw new Error("Docker command failed");
+				throw new UserError("Docker command failed");
 			});
 
 			const result = resolveDockerHost("/no/op/docker");
diff --git a/packages/edge-preview-authenticated-proxy/tests/tsconfig.json b/packages/edge-preview-authenticated-proxy/tests/tsconfig.json
@@ -1,8 +1,8 @@
 {
 	"compilerOptions": {
-		"target": "es2021" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+		"target": "esnext" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
 		"lib": [
-			"es2021"
+			"esnext"
 		] /* Specify a set of bundled library declaration files that describe the target runtime environment. */,
 		"module": "es2022" /* Specify what module code is generated. */,
 		"moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
diff --git a/packages/miniflare/src/index.ts b/packages/miniflare/src/index.ts
@@ -2001,7 +2001,8 @@ export class Miniflare {
 		const maybeSocketPorts = await this.#runtime.updateConfig(
 			configBuffer,
 			runtimeOpts,
-			this.#workerOpts.flatMap((w) => w.core.name ?? [])
+			this.#workerOpts.flatMap((w) => w.core.name ?? []),
+			this.#disposeController.signal
 		);
 		if (this.#disposeController.signal.aborted) return;
 		if (maybeSocketPorts === undefined) {
diff --git a/packages/miniflare/src/runtime/index.ts b/packages/miniflare/src/runtime/index.ts
@@ -4,13 +4,14 @@ import { randomBytes } from "crypto";
 import { Abortable, once } from "events";
 import path from "path";
 import rl from "readline";
-import { Readable } from "stream";
+import { Readable, Transform } from "stream";
 import { $ as $colors, red } from "kleur/colors";
 import workerdPath, {
 	compatibilityDate as supportedCompatibilityDate,
 } from "workerd";
 import { z } from "zod";
 import { SERVICE_LOOPBACK, SOCKET_ENTRY } from "../plugins";
+import { MiniflareCoreError } from "../shared";
 import { Awaitable } from "../workers";
 
 const ControlMessageSchema = z.discriminatedUnion("event", [
@@ -149,14 +150,63 @@ function getInspectorOptions() {
 	}
 }
 
+class StartupLogBuffer {
+	stdoutStream: Transform;
+	stderrStream: Transform;
+	stdoutBuffer: string[] = [];
+	stderrBuffer: string[] = [];
+
+	buffering = true;
+
+	constructor() {
+		this.stdoutStream = new Transform({
+			transform: (chunk, encoding, callback) => {
+				if (this.buffering) {
+					this.stdoutBuffer.push(chunk.toString());
+				}
+				callback(null, chunk);
+			},
+		});
+		this.stderrStream = new Transform({
+			transform: (chunk, encoding, callback) => {
+				if (this.buffering) {
+					this.stderrBuffer.push(chunk.toString());
+				}
+				callback(null, chunk);
+			},
+		});
+	}
+
+	stopBuffering() {
+		this.buffering = false;
+	}
+
+	handleStartupFailure() {
+		const addressInUseLog = this.stderrBuffer.find((chunk) =>
+			chunk.includes("Address already in use; toString() = ")
+		);
+		if (addressInUseLog) {
+			const match = addressInUseLog.match(
+				/Address already in use; toString\(\) = (.+):(.+)/
+			) ?? ["", "unknown", "unknown"];
+
+			throw new MiniflareCoreError(
+				"ERR_ADDRESS_IN_USE",
+				`Address already in use (${match[1]}:${match[2]}). Please check that you are not already running a server on this address or specify a different port with --port.`
+			);
+		}
+	}
+}
+
 export class Runtime {
 	#process?: childProcess.ChildProcess;
 	#processExitPromise?: Promise<void>;
 
 	async updateConfig(
 		configBuffer: Buffer,
 		options: Abortable & RuntimeOptions,
-		workerNames: string[]
+		workerNames: string[],
+		abortSignal: AbortSignal
 	): Promise<SocketPorts | undefined> {
 		// 1. Stop existing process (if any) and wait for exit
 		await this.dispose();
@@ -172,11 +222,16 @@ export class Runtime {
 			stdio: ["pipe", "pipe", "pipe", "pipe"],
 			env: { ...process.env, FORCE_COLOR },
 		});
+		const startupLogBuffer = new StartupLogBuffer();
 		this.#process = runtimeProcess;
 		this.#processExitPromise = waitForExit(runtimeProcess);
 
 		const handleRuntimeStdio = options.handleRuntimeStdio ?? pipeOutput;
-		handleRuntimeStdio(runtimeProcess.stdout, runtimeProcess.stderr);
+
+		handleRuntimeStdio(
+			runtimeProcess.stdout.pipe(startupLogBuffer.stdoutStream),
+			runtimeProcess.stderr.pipe(startupLogBuffer.stderrStream)
+		);
 
 		const controlPipe = runtimeProcess.stdio[3];
 		assert(controlPipe instanceof Readable);
@@ -226,6 +281,13 @@ export class Runtime {
 				p.unref();
 			}
 		}
+
+		startupLogBuffer.stopBuffering();
+
+		if (ports === undefined && !abortSignal.aborted) {
+			startupLogBuffer.handleStartupFailure();
+		}
+
 		return ports;
 	}
 
diff --git a/packages/miniflare/src/shared/error.ts b/packages/miniflare/src/shared/error.ts
diff --git a/packages/wrangler/src/api/startDevWorker/DevEnv.ts b/packages/wrangler/src/api/startDevWorker/DevEnv.ts
diff --git a/packages/wrangler/src/d1/execute.ts b/packages/wrangler/src/d1/execute.ts
diff --git a/packages/wrangler/src/dev/miniflare/stdio.ts b/packages/wrangler/src/dev/miniflare/stdio.ts
diff --git a/packages/wrangler/src/index.ts b/packages/wrangler/src/index.ts

Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,6 @@`
`1`	`1`	`{`
	`2`	`+ "$schema": "node_modules/wrangler/config-schema.json",`
`2`	`3`	`"name": "worker-ts",`
`3`	`4`	`"main": "src/index.ts",`
`4`	`5`	`"compatibility_date": "2023-05-04",`
`5`		`- "hyperdrive": [`
`6`		`- {`
`7`		`- "binding": "H",`
`8`		`- "id": "hello",`
`9`		`- },`
`10`		`- ],`
`11`	`6`	`}`