Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

ts-node fails after switching to type module and module ESNext

ErrorERR_UNKNOWN_FILE_EXTENSION

Short answer

Setting type to module makes Node load your files as native ESM, and plain ts-node does not hook into that loader. Run ts-node with --esm, set esm to true in tsconfig, or pass the loader to Node. Keep package.json and tsconfig.json on the same module system.

  • Applies to ts-node 10, TypeScript 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the two settings that must agree, the package type and the tsconfig module.

    node -p "require('./package.json').type"
    npx tsc --showConfig | grep '"module"'
  2. 2Match what you see, then jump to its fix

    1. 1type is module, module is ESNext, and the command is plain ts-node or node index.ts.The ESM loader is not switched onFix
    2. 2Only one of the two was changed, so type says commonjs while module says ESNext, or the other way round.package.json and tsconfig.json use different module systemsFix
    3. 3The error names a file with no extension, such as the mocha binary, or a config file like webpack.config.ts.A tool such as mocha or a config file starts in ESM without the hookFix
    4. 4A plain script run with ts-node, no type checking needed at run time.You only need to run TypeScript, not compile itFix

What does the error look like?

  • ERR_UNKNOWN_FILE_EXTENSION
  • ERR_REQUIRE_ESM

Cause 1 of 4

The ESM loader is not switched on

1Check

The ts-node docs list three ways to run native ESM: ts-node --esm, ts-node-esm, or esm set to true in tsconfig.

grep -n -A3 '"ts-node"' tsconfig.json

2Fix

Turn the option on in tsconfig, then run ts-node as usual. Or pass the loader to Node.

// tsconfig.json
{
  "compilerOptions": { "module": "ESNext" },
  "ts-node": { "esm": true }
}

# or, without the tsconfig option
node --loader ts-node/esm ./index.ts

3Verify

Run the entry file.

npx ts-node ./index.ts

Confirmed by typestrong.org

Did this fix it?

Cause 2 of 4

package.json and tsconfig.json use different module systems

1Check

ts-node's troubleshooting page says to double-check the package type and the tsconfig module, and to make the project all CommonJS or all native ESM.

cat package.json | grep '"type"' && grep '"module"' tsconfig.json

2Fix

Pick one. For CommonJS, set type to commonjs (or remove it) and module to CommonJS. If a bundler needs ESNext in tsconfig, override only ts-node.

{
  "compilerOptions": { "module": "ESNext" },
  "ts-node": { "compilerOptions": { "module": "CommonJS" } }
}

3Verify

Run the entry file again.

npx ts-node ./index.ts

Confirmed by typestrong.org

Did this fix it?

Cause 3 of 4

A tool such as mocha or a config file starts in ESM without the hook

1Check

Extensionless executables and TypeScript config files are not accepted by native ESM unless ts-node handles them.

npx ts-node -vv

2Fix

Use ts-node 10.6.0 or later for the extensionless case. For a config file, rename it to .cts if the tool allows it.

npm install -D ts-node@latest

3Verify

Run the tool again.

npx mocha

Confirmed by typestrong.org

Did this fix it?

Cause 4 of 4

You only need to run TypeScript, not compile it

1Check

Check the Node.js version. From 22.18.0 and 23.6.0 Node strips types by default.

node --version

2Fix

Run the file with Node directly. Import specifiers must carry the .ts extension, and only erasable syntax works (no enums).

node index.ts
// inside index.ts
import { helper } from './helper.ts'

3Verify

The script runs, and a type-check with tsc still passes.

npx tsc --noEmit

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Change type in package.json and module in tsconfig.json in the same commit.
  • Run the app in CI exactly as production does, with the same Node.js version.
  • Treat ts-node ESM support as experimental: its docs say it is not recommended for production, so build to JavaScript for deploys.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

cdk synth says --app is required

--app is required either in command-line, in cdk.json or in ~/.cdk.json

The CDK CLI needs a command that runs your app and finds it in three places: the --app option, cdk.json in the project folder, or cdk.json in your home folder.

3 causes, each with a fix

Back end

Mocha or Node cannot find ts-node/register

Error: Cannot find module 'ts-node/register'

Node resolves ts-node/register from your project's node_modules, so the package must be installed there, next to typescript.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.