fix: report startup errors before workerd profiling (#10169) (#10182)

* fix: report startup errors before workerd profiling

- Report original startup error message before attempting profiling
- Handle workerd profiling failures gracefully
- Silent profiling failures for deployment errors, reported for manual profiling
- Ensure users see the actual startup error even if profiling fails
- Fixes #10133



* fix: correct error handling in handleStartupError to allow UserError propagation

- Restructure try-catch to only handle profiling failures, not intentional UserError
- Ensure tests receive expected UserError message
- Update PR description to fix validation requirements



* test: add comprehensive tests for handleStartupError function

- Test profiling success with profile information included
- Test silent profiling failures for deployment errors
- Test reported profiling failures for manual profiling
- Test relative path handling in profile output
- Test startup error reporting before profiling attempts



* refactor: show startup errors before profiling attempts

- Log startup error immediately before attempting profiling
- Eliminates duplicate error handling in catch block
- Maintains silent profiling failures for deployment errors
- Maintains reported profiling failures for manual profiling
- Cleaner error handling approach as requested



* fix: resolve Windows path separator issue in test

- Update test assertions to be platform-agnostic
- Check for key path components rather than exact separators
- Fixes Windows CI failure in 'uses relative paths for profile output' test



* rework the friendly validator processing

- moves `printOffendingDependencies()` to the friendly-validator-errors.ts file, which is the only place it is used
- changes the friendly-validator-errors.ts functions to just return error messages that can then be used as needed by client code

* fix: resolve TypeScript error and Windows path separator issue

- Fix Uint8Array generic type error in check/commands.ts
- Update normalizeMessage to handle cross-platform path separators
- Ensure test snapshots work on both Windows and Unix systems



* ensure that slashes are normalized before the startup profile hash

* reuse normalizeString helper

* catch all start-up-profile strings when normalizing

* fixup snapshot & normalization

---------

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: [email protected] <[email protected]>
Co-authored-by: Peter Bacon Darwin <[email protected]>

Author: 3 people

.changeset/long-hairs-feel.md

@@ -0,0 +1,5 @@
+---
+"wrangler": patch
+---
+
+fix: report startup errors before workerd profiling

packages/wrangler/src/__tests__/deploy.test.ts

@@ -10,13 +10,12 @@ import { http, HttpResponse } from "msw";
 import dedent from "ts-dedent";
 import { File } from "undici";
 import { vi } from "vitest";
-import {
-	printBundleSize,
-	printOffendingDependencies,
-} from "../deployment-bundle/bundle-reporter";
+import { printBundleSize } from "../deployment-bundle/bundle-reporter";
 import { clearOutputFilePath } from "../output";
 import { sniffUserAgent } from "../package-manager";
+import { ParseError } from "../parse";
 import { writeAuthConfigFile } from "../user";
+import { diagnoseScriptSizeError } from "../utils/friendly-validator-errors";
 import { mockAccountId, mockApiToken } from "./helpers/mock-account-id";
 import { mockAuthDomain } from "./helpers/mock-auth-domain";
 import { mockConsoleMethods } from "./helpers/mock-console";
@@ -11633,7 +11632,23 @@ export default{
 			expect(std).toMatchInlineSnapshot(`
 				Object {
 				  "debug": "",
-				  "err": "",
+				  "err": "X [ERROR] Your Worker failed validation because it exceeded size limits.
+
+
+				  A request to the Cloudflare API (/accounts/some-account-id/workers/scripts/test-name/versions)
+				  failed.
+				   - workers.api.error.script_too_large [code: 10027]
+				  Here are the 4 largest dependencies included in your script:
+
+				  - index.js - xx KiB
+				  - add.wasm - xx KiB
+				  - dependency.js - xx KiB
+				  - message.txt - xx KiB
+
+				  If these are unnecessary, consider removing them
+
+
+				",
 				  "info": "",
 				  "out": "Total Upload: xx KiB / gzip: xx KiB
 				No bindings found.
@@ -11646,15 +11661,7 @@ export default{
 				  https://github.com/cloudflare/workers-sdk/issues/new/choose
 
 				",
-				  "warn": "▲ [WARNING] Here are the 4 largest dependencies included in your script:
-
-				  - index.js - xx KiB
-				  - add.wasm - xx KiB
-				  - dependency.js - xx KiB
-				  - message.txt - xx KiB
-				  If these are unnecessary, consider removing them
-
-				",
+				  "warn": "",
 				}
 			`);
 		});
@@ -11695,9 +11702,44 @@ export default{
 				main: "index.js",
 			});
 
-			await expect(runWrangler("deploy")).rejects.toThrowError(
-				`Your Worker failed validation because it exceeded startup limits.`
-			);
+			await expect(runWrangler("deploy")).rejects.toThrowError();
+			expect(std).toMatchInlineSnapshot(`
+				Object {
+				  "debug": "",
+				  "err": "X [ERROR] Your Worker failed validation because it exceeded startup limits.
+
+
+				  A request to the Cloudflare API (/accounts/some-account-id/workers/scripts/test-name/versions)
+				  failed.
+				   - Error: Script startup exceeded CPU time limit. [code: 10021]
+
+				  To ensure fast responses, there are constraints on Worker startup, such as how much CPU it can
+				  use, or how long it can take. Your Worker has hit one of these startup limits. Try reducing the
+				  amount of work done during startup (outside the event handler), either by removing code or
+				  relocating it inside the event handler.
+
+				  Refer to https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time for more
+				  details
+				  A CPU Profile of your Worker's startup phase has been written to
+				  .wrangler/tmp/startup-profile-<HASH>/worker.cpuprofile - load it into the Chrome DevTools profiler
+				  (or directly in VSCode) to view a flamegraph.
+
+				",
+				  "info": "",
+				  "out": "Total Upload: xx KiB / gzip: xx KiB
+				No bindings found.
+
+				X [ERROR] A request to the Cloudflare API (/accounts/some-account-id/workers/scripts/test-name/versions) failed.
+
+				  Error: Script startup exceeded CPU time limit. [code: 10021]
+
+				  If you think this is a bug, please open an issue at:
+				  https://github.com/cloudflare/workers-sdk/issues/new/choose
+
+				",
+				  "warn": "",
+				}
+			`);
 		});
 
 		describe("unit tests", () => {
@@ -11742,25 +11784,26 @@ export default{
 					"node_modules/k-mod/module.js": { bytesInOutput: 79 },
 				};
 
-				printOffendingDependencies(deps);
-				expect(std).toMatchInlineSnapshot(`
-			Object {
-			  "debug": "",
-			  "err": "",
-			  "info": "",
-			  "out": "",
-			  "warn": "▲ [WARNING] Here are the 5 largest dependencies included in your script:
+				const message = diagnoseScriptSizeError(
+					new ParseError({ text: "too big" }),
+					deps
+				);
+				expect(message).toMatchInlineSnapshot(`
+					"Your Worker failed validation because it exceeded size limits.
 
-			  - node_modules/d-mod/module.js - xx KiB
-			  - node_modules/g-mod/module.js - xx KiB
-			  - node_modules/e-mod/module.js - xx KiB
-			  - node_modules/i-mod/module.js - xx KiB
-			  - node_modules/j-mod/module.js - xx KiB
-			  If these are unnecessary, consider removing them
+					too big
 
-			",
-			}
-		`);
+					Here are the 5 largest dependencies included in your script:
+
+					- node_modules/d-mod/module.js - 2061.72 KiB
+					- node_modules/g-mod/module.js - 77.05 KiB
+					- node_modules/e-mod/module.js - 8.02 KiB
+					- node_modules/i-mod/module.js - 1.95 KiB
+					- node_modules/j-mod/module.js - 0.88 KiB
+
+					If these are unnecessary, consider removing them
+					"
+				`);
 			});
 		});
 	});

packages/wrangler/src/__tests__/friendly-validator-errors.test.ts

@@ -0,0 +1,137 @@
+import { FormData } from "undici";
+import { describe, expect, it, vi } from "vitest";
+import * as checkCommands from "../check/commands";
+import { logger } from "../logger";
+import { ParseError } from "../parse";
+import { helpIfErrorIsSizeOrScriptStartup } from "../utils/friendly-validator-errors";
+import { mockConsoleMethods } from "./helpers/mock-console";
+import { normalizeString } from "./helpers/normalize";
+import { runInTempDir } from "./helpers/run-in-tmp";
+
+vi.mock("../check/commands", () => ({ analyseBundle: vi.fn() }));
+const mockAnalyseBundle = vi.mocked(checkCommands.analyseBundle);
+
+describe("helpIfErrorIsSizeOrScriptStartup", () => {
+	const std = mockConsoleMethods();
+	runInTempDir();
+	beforeEach(() => {
+		mockAnalyseBundle.mockReset();
+
+		// Ensure logger is set to debug level for testing
+		const loggerLevel = logger.loggerLevel;
+		logger.loggerLevel = "debug";
+		return () => (logger.loggerLevel = loggerLevel); // Restore original logger level after test
+	});
+
+	it("cleanly reports a startup error even if bundle analysis fails", async () => {
+		mockAnalyseBundle.mockRejectedValue(new Error("workerd profiling failed"));
+
+		expect(
+			await helpIfErrorIsSizeOrScriptStartup(
+				makeStartupError("Script startup exceeded CPU limit."),
+				{}, // no dependencies
+				new FormData(), // mock worker bundle
+				"/test"
+			)
+		).toMatchInlineSnapshot(`
+				"Your Worker failed validation because it exceeded startup limits.
+
+				Deploy failed
+				 - Script startup exceeded CPU limit.
+
+				To ensure fast responses, there are constraints on Worker startup, such as how much CPU it can use, or how long it can take. Your Worker has hit one of these startup limits. Try reducing the amount of work done during startup (outside the event handler), either by removing code or relocating it inside the event handler.
+
+				Refer to https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time for more details"
+			`);
+
+		expect(std).toMatchInlineSnapshot(`
+			Object {
+			  "debug": "An error occurred while trying to locally profile the Worker: Error: workerd profiling failed",
+			  "err": "",
+			  "info": "",
+			  "out": "",
+			  "warn": "",
+			}
+		`);
+	});
+
+	it("reports size errors even if bundle analysis would fail", async () => {
+		mockAnalyseBundle.mockRejectedValue(new Error("workerd profiling failed"));
+
+		expect(
+			await helpIfErrorIsSizeOrScriptStartup(
+				makeScriptSizeError("Script size exceeded limits."),
+				{ "test.js": { bytesInOutput: 1000 } }, // mock dependencies
+				new FormData(), // mock worker bundle
+				"/test"
+			)
+		).toMatchInlineSnapshot(`
+			"Your Worker failed validation because it exceeded size limits.
+
+			Script size exceeded limits.
+
+			Here are the 1 largest dependencies included in your script:
+
+			- test.js - 0.98 KiB
+
+			If these are unnecessary, consider removing them
+			"
+		`);
+		expect(std).toMatchInlineSnapshot(`
+			Object {
+			  "debug": "",
+			  "err": "",
+			  "info": "",
+			  "out": "",
+			  "warn": "",
+			}
+		`);
+	});
+
+	it("includes profile information when bundle analysis succeeds", async () => {
+		mockAnalyseBundle.mockResolvedValue({ nodes: [], samples: [] });
+
+		const message = await helpIfErrorIsSizeOrScriptStartup(
+			makeStartupError("Exceeded startup limits."),
+			{}, // no dependencies
+			new FormData(), // mock worker bundle
+			process.cwd() // mock project root (the tmp dir)
+		);
+
+		expect(normalizeString(message ?? "")).toMatchInlineSnapshot(`
+			"Your Worker failed validation because it exceeded startup limits.
+
+			Deploy failed
+			 - Exceeded startup limits.
+
+			To ensure fast responses, there are constraints on Worker startup, such as how much CPU it can use, or how long it can take. Your Worker has hit one of these startup limits. Try reducing the amount of work done during startup (outside the event handler), either by removing code or relocating it inside the event handler.
+
+			Refer to https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time for more details
+			A CPU Profile of your Worker's startup phase has been written to .wrangler/tmp/startup-profile-<HASH>/worker.cpuprofile - load it into the Chrome DevTools profiler (or directly in VSCode) to view a flamegraph."
+		`);
+		expect(std).toMatchInlineSnapshot(`
+			Object {
+			  "debug": "",
+			  "err": "",
+			  "info": "",
+			  "out": "",
+			  "warn": "",
+			}
+		`);
+	});
+});
+
+function makeScriptSizeError(text: string): ParseError {
+	const error = new ParseError({ text });
+	Object.assign(error, { code: 10027 });
+	return error;
+}
+
+function makeStartupError(message: string): ParseError {
+	const error = new ParseError({
+		text: "Deploy failed",
+		notes: [{ text: message }],
+	});
+	Object.assign(error, { code: 10021 });
+	return error;
+}

packages/wrangler/src/__tests__/helpers/normalize.ts

@@ -5,12 +5,21 @@ export function normalizeString(input: string): string {
 	return normalizeErrorMarkers(
 		replaceByte(
 			stripTrailingWhitespace(
-				normalizeSlashes(normalizeCwd(normalizeTempDirs(stripTimings(input))))
+				stripStartupProfileHash(
+					normalizeSlashes(normalizeCwd(normalizeTempDirs(stripTimings(input))))
+				)
 			)
 		)
 	);
 }
 
+/**
+ * Replace the non-deterministic hash in a startup-profile path with a placeholder.
+ */
+function stripStartupProfileHash(str: string): string {
+	return str.replace(/startup-profile-[^/]+/g, "startup-profile-<HASH>");
+}
+
 /**
  * Normalize error `X` markers.
  *

packages/wrangler/src/check/commands.ts

@@ -138,9 +138,9 @@ export const checkStartupCommand = createCommand({
 
 async function getEntryValue(
 	entry: FormDataEntryValue
-): Promise<Uint8Array<ArrayBuffer> | string> {
+): Promise<Uint8Array | string> {
 	if (entry instanceof Blob) {
-		return new Uint8Array(await entry.arrayBuffer());
+		return new Uint8Array((await entry.arrayBuffer()) as ArrayBuffer);
 	} else {
 		return entry as string;
 	}
@@ -166,11 +166,14 @@ async function convertWorkerBundleToModules(
 	workerBundle: FormData
 ): Promise<ModuleDefinition[]> {
 	return await Promise.all(
-		[...workerBundle.entries()].map(async (m) => ({
-			type: getModuleType(m[1]),
-			path: m[0],
-			contents: await getEntryValue(m[1]),
-		}))
+		[...workerBundle.entries()].map(
+			async (m) =>
+				({
+					type: getModuleType(m[1]),
+					path: m[0],
+					contents: await getEntryValue(m[1]),
+				}) as ModuleDefinition
+		)
 	);
 }
 

packages/wrangler/src/deploy/deploy.ts

@@ -888,12 +888,15 @@ See https://developers.cloudflare.com/workers/platform/compatibility-dates for m
 				if (!bindingsPrinted) {
 					printBindings({ ...withoutStaticAssets, vars: maskedVars });
 				}
-				await helpIfErrorIsSizeOrScriptStartup(
+				const message = await helpIfErrorIsSizeOrScriptStartup(
 					err,
 					dependencies,
 					workerBundle,
 					props.projectRoot
 				);
+				if (message !== null) {
+					logger.error(message);
+				}
 
 				// Apply source mapping to validation startup errors if possible
 				if (