feat: add friendly error for unloadable virtual modules

sapphi-red · sapphi-red · commit 85a58aee593c · 2026-03-30T13:27:32.000+09:00
diff --git a/crates/rolldown_error/src/build_diagnostic/events/unloadable_dependency.rs b/crates/rolldown_error/src/build_diagnostic/events/unloadable_dependency.rs
@@ -63,5 +63,11 @@ impl BuildEvent for UnloadableDependency {
         diagnostic.title = self.message(opts);
       }
     }
+
+    if self.resolved.starts_with("\\0") {
+      diagnostic.add_help(String::from(
+        "This module seems to be a virtual module, but no plugin handled it via the load hook.",
+      ));
+    }
   }
 }
diff --git a/packages/rolldown/tests/fixtures/misc/error/unloadable-virtual-module/_config.ts b/packages/rolldown/tests/fixtures/misc/error/unloadable-virtual-module/_config.ts
@@ -0,0 +1,34 @@
+import { defineTest } from 'rolldown-tests';
+import { stripVTControlCharacters } from 'node:util';
+import { expect } from 'vitest';
+
+export default defineTest({
+  config: {
+    plugins: [
+      {
+        name: 'test-virtual',
+        resolveId(id) {
+          if (id === 'virtual-module') {
+            return '\0virtual-module';
+          }
+        },
+        // intentionally no load hook
+      },
+    ],
+  },
+  catchError(e: any) {
+    for (const error of e.errors) {
+      error.message = stripVTControlCharacters(error.message);
+    }
+    expect(e.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'UNLOADABLE_DEPENDENCY',
+          message: expect.stringContaining(
+            'This module seems to be a virtual module, but no plugin handled it via the load hook.',
+          ),
+        }),
+      ]),
+    );
+  },
+});
diff --git a/packages/rolldown/tests/fixtures/misc/error/unloadable-virtual-module/main.js b/packages/rolldown/tests/fixtures/misc/error/unloadable-virtual-module/main.js
@@ -0,0 +1 @@
+import 'virtual-module';

Original file line number	Diff line number	Diff line change
`@@ -63,5 +63,11 @@ impl BuildEvent for UnloadableDependency {`
`63`	`63`	`diagnostic.title = self.message(opts);`
`64`	`64`	`}`
`65`	`65`	`}`
	`66`	`+`
	`67`	`+ if self.resolved.starts_with("\\0") {`
	`68`	`+ diagnostic.add_help(String::from(`
	`69`	`+ "This module seems to be a virtual module, but no plugin handled it via the load hook.",`
	`70`	`+ ));`
	`71`	`+ }`
`66`	`72`	`}`
`67`	`73`	`}`