ts-node fails after switching to type module and module ESNext
ERR_UNKNOWN_FILE_EXTENSIONShort 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.
Fix it fast
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"'2Match what you see, then jump to its fix
- 1
type is module, module is ESNext, and the command is plain ts-node or node index.ts.The ESM loader is not switched onFix - 2
Only 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
The 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
A plain script run with ts-node, no type checking needed at run time.You only need to run TypeScript, not compile itFix
- 1
What does the error look like?
ERR_UNKNOWN_FILE_EXTENSIONERR_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.json2Fix
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.ts3Verify
Run the entry file.
npx ts-node ./index.tsConfirmed by typestrong.org
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.json2Fix
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.tsConfirmed by typestrong.org
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 -vv2Fix
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@latest3Verify
Run the tool again.
npx mochaConfirmed by typestrong.org
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 --version2Fix
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 --noEmitConfirmed by nodejs.org
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
ts-node stops with 'TSError: ⨯ Unable to compile TypeScript'
src/index.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
ts-node type checks every file before it runs it, so a TSError is a normal TypeScript compile error shown by ts-node.
4 causes, each with a fixBack end
TypeScript cannot find '@angular/platform-browser' in an Angular project
Cannot find module '@angular/platform-browser' or its corresponding type declarations.
TS2307 means TypeScript could not turn the import into a file.
3 causes, each with a fixBack end
Angular build fails with TS2707 or "has no exported member" after installing a library
Module '"@angular/core"' has no exported member
These errors mean a library was compiled by a newer Angular than your app uses.
3 causes, each with a fixBack 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 fixBack end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fixBack 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