Improve error message when modules cannot be resolved during bundling

[dario-piotrowicz]

Fixes #7095

When a module cannot be resolved during bundling, Wrangler now suggests using the alias configuration option to substitute it with an alternative implementation. This replaces esbuild's default suggestion to "mark the path as external", which is not a supported option in Wrangler.

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s): Improve error message when modules cannot be resolved during bundling #12931
  • Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 8e2b0ff

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

✅ All changesets look good

[ask-bonk]

The handle-errors.ts path at lines 564-569 just logs the build failure errors - by the time execution reaches this code, the error has already been thrown from bundleWorker in bundle.ts where the rewrites happened. So the rewritten error messages will be properly displayed. Good.

Now let me review everything I've seen and assess:

Summary of changes:

1. New rewriteUnresolvedModuleBuildFailure function in build-failures.ts that replaces esbuild's "mark as external" suggestion with a Wrangler-specific suggestion to use alias.
2. The function is called in bundle.ts right after the existing rewriteNodeCompatBuildFailure.
3. Tests in both BundleController.test.ts (dev path) and build.test.ts (deploy path).
4. Changeset included.

Assessment:

• The logic is correct: it matches Could not resolve "X" errors, skips Node builtins (handled by the other function), and only rewrites when esbuild's "mark as external" note is present.
• The ordering of the two rewrite functions doesn't matter because rewriteUnresolvedModuleBuildFailure checks the error.text (which isn't modified by rewriteNodeCompatBuildFailure) to skip Node builtins.
• Tests cover both the positive case (non-Node module) and the negative case (Node builtin) in both code paths.
• The test patterns match the existing conventions in the file.
• The changeset is properly formatted as a patch.
• No security, backward compatibility, or logic issues found.

LGTM

github run

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@12931

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@12931

miniflare

npm i https://pkg.pr.new/miniflare@12931

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@12931

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@12931

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@12931

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@12931

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@12931

wrangler

npm i https://pkg.pr.new/wrangler@12931

commit: 8e2b0ff

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

[petebacondarwin]

Happy to have an improved error message here. I left a comment about the actual content of the message as I think we could be more concrete and helpful.