Node.js ESM/CommonJS Error Explainer

The same error has a different fix on Node.js 20.11 and on 22.12. Paste the error, add your package.json and node -v if you have them, and get the cause plus the least invasive fix for the version you actually run — each one linked to the Node.js documentation or release notes it comes from.

Runs entirely in your browser — nothing you paste is sent anywhere. Tokens and passwords that appear in paths or URLs are masked in the output.

Paste the error (the full output, including the Node.js vX.Y.Z line if present)

Optional: package.json, file extension, Node.js version (sharper advice)

package.json (or just type / exports / main / scripts)

Failing file extension

Node.js version (node -v)

Try:

What gets explained

ERR_REQUIRE_ESM / ERR_REQUIRE_ASYNC_MODULE

require() of an ES module. Node.js loads synchronous ES modules through require() by default from 23.0.0, 22.12.0 and 20.19.0 — the advice changes on either side of that line.

Cannot use import statement outside a module

which marker (.mjs/.cjs, "type") decided CommonJS, and whether your Node.js has syntax detection on by default (22.7.0+, 20.19.0+).

require / exports / module / __dirname is not defined in ES module scope

a CommonJS file running as ESM: rename to .cjs, createRequire, or import.meta.dirname (21.2.0+, 20.11.0+).

ERR_UNKNOWN_FILE_EXTENSION ".ts"

built-in type stripping (flag from 22.6.0, on by default from 23.6.0 and 22.18.0), tsx, or ts-node’s ESM loader.

ERR_MODULE_NOT_FOUND / ERR_UNSUPPORTED_DIR_IMPORT

relative imports without a file extension or pointing at a folder — ESM never guesses.

SyntaxError: Unexpected identifier 'assert'

import assertions were dropped in Node.js 22.0.0; import attributes use with.

ERR_PACKAGE_PATH_NOT_EXPORTED

a deep import that the package’s "exports" map does not allow, or no entry for require()/import.

How Node.js picks ESM or CommonJS

Per file, not per project: .mjs is always an ES module, .cjs is always CommonJS, and .js follows the "type" field of the nearest package.json. With no "type" field, newer Node.js versions inspect the file and run it as ESM when it contains import or export.

That is why the explainer asks for the extension, the type field and the version: together they decide which loader ran your file — and so which fix is the smallest one.

Build failing for another reason?

Paste the output into the Build Error Decoder, or browse the other free tools.

All tools

Step-by-step fixes for these errors

This tool runs on dev-error-explainers, an open-source, zero-dependency library — view the source on GitHub.