esm: improve error messages for ambiguous module syntax

mag123c · aduh95 · commit 311a04cf2d88 · 2026-01-19T19:19:19.000+01:00
PR-URL: #60376 Fixes: #60322 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
diff --git a/lib/internal/modules/esm/module_job.js b/lib/internal/modules/esm/module_job.js
@@ -2,9 +2,9 @@
 
 const {
   Array,
+  ArrayPrototypeFind,
   ArrayPrototypeJoin,
   ArrayPrototypePush,
-  ArrayPrototypeSome,
   FunctionPrototype,
   ObjectSetPrototypeOf,
   PromisePrototypeThen,
@@ -65,8 +65,8 @@ const CJSGlobalLike = [
   '__filename',
   '__dirname',
 ];
-const isCommonJSGlobalLikeNotDefinedError = (errorMessage) =>
-  ArrayPrototypeSome(
+const findCommonJSGlobalLikeNotDefinedError = (errorMessage) =>
+  ArrayPrototypeFind(
     CJSGlobalLike,
     (globalLike) => errorMessage === `${globalLike} is not defined`,
   );
@@ -79,11 +79,28 @@ const isCommonJSGlobalLikeNotDefinedError = (errorMessage) =>
  * @returns {void}
  */
 const explainCommonJSGlobalLikeNotDefinedError = (e, url, hasTopLevelAwait) => {
-  if (e?.name === 'ReferenceError' &&
-      isCommonJSGlobalLikeNotDefinedError(e.message)) {
+  const notDefinedGlobalLike = e?.name === 'ReferenceError' && findCommonJSGlobalLikeNotDefinedError(e.message);
 
+  if (notDefinedGlobalLike) {
     if (hasTopLevelAwait) {
-      e.message = `Cannot determine intended module format because both require() and top-level await are present. If the code is intended to be CommonJS, wrap await in an async function. If the code is intended to be an ES module, replace require() with import.`;
+      let advice;
+      switch (notDefinedGlobalLike) {
+        case 'require':
+          advice = 'replace require() with import';
+          break;
+        case 'module':
+        case 'exports':
+          advice = 'use export instead of module.exports/exports';
+          break;
+        case '__filename':
+          advice = 'use import.meta.filename instead';
+          break;
+        case '__dirname':
+          advice = 'use import.meta.dirname instead';
+          break;
+      }
+
+      e.message = `Cannot determine intended module format because both '${notDefinedGlobalLike}' and top-level await are present. If the code is intended to be CommonJS, wrap await in an async function. If the code is intended to be an ES module, ${advice}.`;
       e.code = 'ERR_AMBIGUOUS_MODULE_SYNTAX';
       return;
     }
diff --git a/test/es-module/test-esm-detect-ambiguous.mjs b/test/es-module/test-esm-detect-ambiguous.mjs
@@ -283,7 +283,7 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
 
       assert.match(
         stderr,
-        /ReferenceError: Cannot determine intended module format because both require\(\) and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+        /ReferenceError: Cannot determine intended module format because both 'require' and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
       );
       assert.strictEqual(stdout, '');
       assert.strictEqual(code, 1);
@@ -440,7 +440,61 @@ describe('cjs & esm ambiguous syntax case', () => {
 
     assert.match(
       stderr,
-      /ReferenceError: Cannot determine intended module format because both require\(\) and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+      /ReferenceError: Cannot determine intended module format because both 'require' and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, replace require\(\) with import\./
+    );
+
+    assert.strictEqual(code, 1);
+    assert.strictEqual(signal, null);
+  });
+
+  it('should throw an ambiguous syntax error when using top-level await with exports', async () => {
+    const { stderr, code, signal } = await spawnPromisified(
+      process.execPath,
+      [
+        '--eval',
+        `exports.foo = 'bar';\nawait 1;`,
+      ]
+    );
+
+    assert.match(
+      stderr,
+      /ReferenceError: Cannot determine intended module format because both 'exports' and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, use export instead of module\.exports\/exports\./
+    );
+
+    assert.strictEqual(code, 1);
+    assert.strictEqual(signal, null);
+  });
+
+  it('should throw an ambiguous syntax error when using top-level await with __filename', async () => {
+    const { stderr, code, signal } = await spawnPromisified(
+      process.execPath,
+      [
+        '--eval',
+        `console.log(__filename);\nawait 1;`,
+      ]
+    );
+
+    assert.match(
+      stderr,
+      /ReferenceError: Cannot determine intended module format because both '__filename' and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, use import\.meta\.filename instead\./
+    );
+
+    assert.strictEqual(code, 1);
+    assert.strictEqual(signal, null);
+  });
+
+  it('should throw an ambiguous syntax error when using top-level await with __dirname', async () => {
+    const { stderr, code, signal } = await spawnPromisified(
+      process.execPath,
+      [
+        '--eval',
+        `console.log(__dirname);\nawait 1;`,
+      ]
+    );
+
+    assert.match(
+      stderr,
+      /ReferenceError: Cannot determine intended module format because both '__dirname' and top-level await are present\. If the code is intended to be CommonJS, wrap await in an async function\. If the code is intended to be an ES module, use import\.meta\.dirname instead\./
     );
 
     assert.strictEqual(code, 1);
