Improve the `ERR_AMBIGUOUS_MODULE_SYNTAX` error message

[avivkeller]

module.exports;

await 1;

The above code snippet causes an ERR_AMBIGUOUS_MODULE_SYNTAX error, since module.exports cannot be used (CJS) in an ESM file. However, the error logged to the console, shown below, incorrectly assumes the error stems from the use of a require()

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.

[avivkeller]

A more fitting error would be

ReferenceError: Cannot determine intended module format because both CommonJS and ES module syntax are present

[aduh95]

A more fitting error would be

ReferenceError: Cannot determine intended module format because both CommonJS and ES module syntax are present

There's no such thing as "CJS syntax", it's just JavaScript – in this case, if the file cannot be loaded as ESM is not a syntax problem, but the use of an undeclared identifier that does not map to a global.
The current message is more more correct – except that it mentions require() instead of module.

[joyeecheung]

I agree with @aduh95 - the proposed version wasn't correct either. The correction should probably be something like

ReferenceError: Cannot determine intended module format because both a global reference to module 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, do not use an undefined global reference to module.

(i.e. changing require() to module, or if it's exports, __filename__ etc., adjust accordingly).

[joyeecheung]

Marking it as a first good issue, I think it can be fixed by updating

node/lib/internal/modules/esm/module_job.js

Lines 78 to 85 in c742220

	if (e?.name === 'ReferenceError' &&
	isCommonJSGlobalLikeNotDefinedError(e.message)) {
	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.`;
	e.code = 'ERR_AMBIGUOUS_MODULE_SYNTAX';
	return;
	}

And replace require() in the message with what gets detected by isCommonJSGlobalLikeNotDefinedError() as the undefined global. Also, the last instruction should change depending on exactly what undefined global is referenced. require/__filename__/__dirname__ may have alternatives in ESM, but module.exports/exports don't necessarily (only writes to them have equivalents, reads to them do not)

[tysoncung]

I noticed this issue. Have you tried checking the error logs or console output? That might help narrow down the root cause. I'd be happy to help investigate if you can share more details about your environment (OS, version, etc.).

[mag123c]

I'd like to work on this issue. I'll update the error message in lib/internal/modules/esm/module_job.js to reference the actual undefined global as suggested.

--

I've opened PR. The changes include:

• Updated error messages to reference the actual undefined global (require, module, exports, __filename, __dirname)
• Added context-specific migration advice for each type of global
• Added test coverage for the new error messages

[Mishradity]

can you assign it to me