Improve error messages and stack traces (#10632)

jamesopstad · web-flow · commit 60631d5ab443 · 2025-09-15T15:53:24.000+01:00
* Capture errors thrown in the default export of the entry Worker in order to preserve stack traces

* Add errors playground

* Add tests

* Add changeset

* Fix lock file
diff --git a/.changeset/olive-rockets-find.md b/.changeset/olive-rockets-find.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+Ensure that correct error messages and stack traces are displayed.
diff --git a/packages/vite-plugin-cloudflare/playground/errors/__tests__/errors.spec.ts b/packages/vite-plugin-cloudflare/playground/errors/__tests__/errors.spec.ts
@@ -0,0 +1,94 @@
+import { describe, expect, test } from "vitest";
+import { isBuild, page, viteTestUrl } from "../../__test-utils__";
+
+describe.runIf(!isBuild)(
+	"error thrown in the default export of the entry Worker",
+	async () => {
+		test("displays the correct message", async () => {
+			await page.goto(`${viteTestUrl}/default-export`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const message = await errorOverlay
+				.locator(".message-body")
+				.first()
+				.textContent();
+			expect(message).toMatch("a is not defined");
+		});
+
+		test("displays the correct source link in the stack trace", async () => {
+			await page.goto(`${viteTestUrl}/default-export`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const stack = errorOverlay.locator(".stack");
+			const fileLink = await stack.locator(".file-link").first().textContent();
+			expect(fileLink).toMatch(/\/errors\/src\/worker-a\/index.ts:24:17$/);
+		});
+	}
+);
+
+describe.runIf(!isBuild)(
+	"error thrown in a named entrypoint of the entry Worker",
+	async () => {
+		test("displays the correct message", async () => {
+			await page.goto(`${viteTestUrl}/named-entrypoint`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const message = await errorOverlay
+				.locator(".message-body")
+				.first()
+				.textContent();
+			expect(message).toMatch("b is not defined");
+		});
+
+		test("displays the correct source link in the stack trace", async () => {
+			await page.goto(`${viteTestUrl}/named-entrypoint`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const stack = errorOverlay.locator(".stack");
+			const fileLink = await stack.locator(".file-link").first().textContent();
+			expect(fileLink).toMatch(/\/errors\/src\/worker-a\/index.ts:30:22$/);
+		});
+	}
+);
+
+describe.runIf(!isBuild)(
+	"error thrown in the default export of an auxiliary Worker",
+	async () => {
+		test("displays the correct message", async () => {
+			await page.goto(`${viteTestUrl}/auxiliary-worker/default-export`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const message = await errorOverlay
+				.locator(".message-body")
+				.first()
+				.textContent();
+			expect(message).toMatch("c is not defined");
+		});
+
+		test("displays the correct source link in the stack trace", async () => {
+			await page.goto(`${viteTestUrl}/auxiliary-worker/default-export`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const stack = errorOverlay.locator(".stack");
+			const fileLink = await stack.locator(".file-link").first().textContent();
+			expect(fileLink).toMatch(/\/errors\/src\/worker-a\/index.ts:36:22$/);
+		});
+	}
+);
+
+describe.runIf(!isBuild)(
+	"error thrown in a named entrypoint of an auxiliary Worker",
+	async () => {
+		test("displays the correct message", async () => {
+			await page.goto(`${viteTestUrl}/auxiliary-worker/named-entrypoint`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const message = await errorOverlay
+				.locator(".message-body")
+				.first()
+				.textContent();
+			expect(message).toMatch("d is not defined");
+		});
+
+		test("displays the correct source link in the stack trace", async () => {
+			await page.goto(`${viteTestUrl}/auxiliary-worker/named-entrypoint`);
+			const errorOverlay = page.locator("vite-error-overlay");
+			const stack = errorOverlay.locator(".stack");
+			const fileLink = await stack.locator(".file-link").first().textContent();
+			expect(fileLink).toMatch(/\/errors\/src\/worker-a\/index.ts:42:22$/);
+		});
+	}
+);
diff --git a/packages/vite-plugin-cloudflare/playground/errors/package.json b/packages/vite-plugin-cloudflare/playground/errors/package.json
@@ -0,0 +1,19 @@
+{
+	"name": "@playground/errors",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build --app",
+		"check:types": "tsc --build",
+		"dev": "vite dev",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "catalog:default",
+		"typescript": "catalog:default",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "workspace:*"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/src/worker-a/index.ts b/packages/vite-plugin-cloudflare/playground/errors/src/worker-a/index.ts
@@ -0,0 +1,51 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+interface Env {
+	NAMED_ENTRYPOINT: Service<NamedEntrypoint>;
+	AUXILIARY_WORKER: Service;
+}
+
+export class NamedEntrypoint extends WorkerEntrypoint {
+	override fetch() {
+		// @ts-expect-error: deliberate error
+		console.log(b);
+
+		return new Response("Named entrypoint");
+	}
+}
+
+export default {
+	async fetch(request, env) {
+		const url = new URL(request.url);
+
+		switch (url.pathname) {
+			case "/default-export": {
+				// @ts-expect-error: deliberate error
+				console.log(a);
+
+				return new Response("Default export");
+			}
+			case "/named-entrypoint": {
+				// Note: if the response is returned directly then the stack trace is incorrect
+				const response = await env.NAMED_ENTRYPOINT.fetch(request);
+
+				return response;
+			}
+			case "/auxiliary-worker/default-export": {
+				// Note: if the response is returned directly then the stack trace is incorrect
+				const response = await env.AUXILIARY_WORKER.fetch(request);
+
+				return response;
+			}
+			case "/auxiliary-worker/named-entrypoint": {
+				// Note: if the response is returned directly then the stack trace is incorrect
+				const response = await env.AUXILIARY_WORKER.fetch(request);
+
+				return response;
+			}
+			default: {
+				return new Response("Fallback");
+			}
+		}
+	},
+} satisfies ExportedHandler<Env>;
diff --git a/packages/vite-plugin-cloudflare/playground/errors/src/worker-a/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/errors/src/worker-a/wrangler.jsonc
@@ -0,0 +1,17 @@
+{
+	"$schema": "../../node_modules/wrangler/config-schema.json",
+	"name": "worker-a",
+	"main": "./index.ts",
+	"compatibility_date": "2024-12-30",
+	"services": [
+		{
+			"binding": "NAMED_ENTRYPOINT",
+			"service": "worker-a",
+			"entrypoint": "NamedEntrypoint",
+		},
+		{
+			"binding": "AUXILIARY_WORKER",
+			"service": "worker-b",
+		},
+	],
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/src/worker-b/index.ts b/packages/vite-plugin-cloudflare/playground/errors/src/worker-b/index.ts
@@ -0,0 +1,35 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+interface Env {
+	NAMED_ENTRYPOINT: Service<NamedEntrypoint>;
+}
+
+export class NamedEntrypoint extends WorkerEntrypoint {
+	override fetch() {
+		// @ts-expect-error: deliberate error
+		console.log(d);
+
+		return new Response("Auxiliary Worker named entrypoint");
+	}
+}
+
+export default {
+	async fetch(request, env) {
+		const url = new URL(request.url);
+
+		switch (url.pathname) {
+			case "/auxiliary-worker/default-export": {
+				// @ts-expect-error: deliberate error
+				console.log(c);
+
+				return new Response("Auxiliary Worker default export");
+			}
+			case "/auxiliary-worker/named-entrypoint": {
+				return env.NAMED_ENTRYPOINT.fetch(request);
+			}
+			default: {
+				return new Response("Auxiliary Worker fallback");
+			}
+		}
+	},
+} satisfies ExportedHandler<Env>;
diff --git a/packages/vite-plugin-cloudflare/playground/errors/src/worker-b/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/errors/src/worker-b/wrangler.jsonc
@@ -0,0 +1,13 @@
+{
+	"$schema": "../../node_modules/wrangler/config-schema.json",
+	"name": "worker-b",
+	"main": "./index.ts",
+	"compatibility_date": "2024-12-30",
+	"services": [
+		{
+			"binding": "NAMED_ENTRYPOINT",
+			"service": "worker-b",
+			"entrypoint": "NamedEntrypoint",
+		},
+	],
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/tsconfig.json b/packages/vite-plugin-cloudflare/playground/errors/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/tsconfig.node.json b/packages/vite-plugin-cloudflare/playground/errors/tsconfig.node.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/base.json"],
+	"include": ["vite.config.ts", "__tests__"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/tsconfig.worker.json b/packages/vite-plugin-cloudflare/playground/errors/tsconfig.worker.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
+	"include": ["src"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/turbo.json b/packages/vite-plugin-cloudflare/playground/errors/turbo.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"outputs": ["dist/**"]
+		}
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/errors/vite.config.ts b/packages/vite-plugin-cloudflare/playground/errors/vite.config.ts
@@ -0,0 +1,13 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		cloudflare({
+			configPath: "./src/worker-a/wrangler.jsonc",
+			auxiliaryWorkers: [{ configPath: "./src/worker-b/wrangler.jsonc" }],
+			inspectorPort: false,
+			persistState: false,
+		}),
+	],
+});
diff --git a/packages/vite-plugin-cloudflare/src/cloudflare-environment.ts b/packages/vite-plugin-cloudflare/src/cloudflare-environment.ts
@@ -4,6 +4,7 @@ import * as vite from "vite";
 import { MAIN_ENTRY_NAME } from "./constants";
 import {
 	INIT_PATH,
+	IS_ENTRY_WORKER_HEADER,
 	UNKNOWN_HOST,
 	VIRTUAL_WORKER_ENTRY,
 	WORKER_ENTRY_PATH_HEADER,
@@ -95,7 +96,8 @@ export class CloudflareDevEnvironment extends vite.DevEnvironment {
 
 	async initRunner(
 		worker: ReplaceWorkersTypes<Fetcher>,
-		workerConfig: WorkerConfig
+		workerConfig: WorkerConfig,
+		isEntryWorker: boolean
 	) {
 		this.#worker = worker;
 
@@ -104,6 +106,7 @@ export class CloudflareDevEnvironment extends vite.DevEnvironment {
 			{
 				headers: {
 					[WORKER_ENTRY_PATH_HEADER]: workerConfig.main,
+					[IS_ENTRY_WORKER_HEADER]: String(isEntryWorker),
 					upgrade: "websocket",
 				},
 			}
@@ -251,12 +254,14 @@ export function initRunners(
 			async ([environmentName, workerConfig]) => {
 				debuglog("Initializing worker:", workerConfig.name);
 				const worker = await miniflare.getWorker(workerConfig.name);
+				const isEntryWorker =
+					environmentName === resolvedPluginConfig.entryWorkerEnvironmentName;
 
 				return (
 					viteDevServer.environments[
 						environmentName
 					] as CloudflareDevEnvironment
-				).initRunner(worker, workerConfig);
+				).initRunner(worker, workerConfig, isEntryWorker);
 			}
 		)
 	);
diff --git a/packages/vite-plugin-cloudflare/src/runner-worker/errors.ts b/packages/vite-plugin-cloudflare/src/runner-worker/errors.ts
@@ -0,0 +1,43 @@
+// Note: the approach used here has the following implications:
+// - Errors that occur in named entrypoints, auxiliary Workers etc. will display in stack traces as occurring in the default export of the entry Worker
+// - If an error occurs in a named entrypoint or auxiliary Worker and the `fetch` handler in the default export of the entry Worker returns the response from the binding directly then the stack trace will be incorrect
+
+/**
+ * Converts an error to an object that can be be serialized and revived by Miniflare.
+ * Copied from `packages/wrangler/templates/middleware/middleware-miniflare3-json-error.ts`
+ */
+function reduceError(e: any): any {
+	return {
+		name: e?.name,
+		message: e?.message ?? String(e),
+		stack: e?.stack,
+		cause: e?.cause === undefined ? undefined : reduceError(e.cause),
+	};
+}
+
+/**
+ * Captures errors in the `fetch` handler of the default export of the entry Worker.
+ * These are returned as a JSON response that is revived by Miniflare.
+ * See comment in `/packages/wrangler/src/deployment-bundle/bundle.ts` for more info.
+ */
+export async function maybeCaptureError<T>(
+	options: { isEntryWorker: boolean; key: string; exportName: string },
+	fn: () => T
+) {
+	if (
+		!options.isEntryWorker ||
+		options.exportName !== "default" ||
+		options.key !== "fetch"
+	) {
+		return fn();
+	}
+
+	try {
+		return await fn();
+	} catch (error) {
+		return Response.json(reduceError(error), {
+			status: 500,
+			headers: { "MF-Experimental-Error-Stack": "true" },
+		});
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/src/runner-worker/index.ts b/packages/vite-plugin-cloudflare/src/runner-worker/index.ts
diff --git a/packages/vite-plugin-cloudflare/src/runner-worker/module-runner.ts b/packages/vite-plugin-cloudflare/src/runner-worker/module-runner.ts
diff --git a/packages/vite-plugin-cloudflare/src/shared.ts b/packages/vite-plugin-cloudflare/src/shared.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@cloudflare/vite-plugin": patch
 +---
++
 +Ensure that correct error messages and stack traces are displayed.