ts-node stops with 'TSError: ⨯ Unable to compile TypeScript'
TSError: ⨯ Unable to compile TypeScript:Short answer
ts-node type checks every file before it runs it, so a TSError is a normal TypeScript compile error shown by ts-node. Read the diagnostic code under the message and fix that line. Missing types and wrong module settings are the other usual causes; transpile-only mode skips the check but hides real bugs.
Fix it fast
1Find out which cause you have
Run the same check TypeScript itself would run. If tsc reports the same error, the problem is your code or config, not ts-node. Also print the config ts-node really uses.
npx tsc --noEmit npx ts-node --showConfig2Match what you see, then jump to its fix
- 1
file(line,col): error TSxxxx right under the TSError lineA real type error in the file named in the messageFix - 2
Cannot find name 'process' or Cannot find module, though the package is installedType declarations are not loadedFix - 3
ERR_UNKNOWN_FILE_EXTENSION or ERR_REQUIRE_ESMESM project run without the ESM loaderFix - 4
Large project, slow start, and the type check already runs in the editor or CIYou only need speed in development, and types are checked elsewhereFix
- 1
What does the error look like?
TSError: ⨯ Unable to compile TypeScript:src/index.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"
Cause 1 of 4
A real type error in the file named in the message
1Check
Errors from ts-node are the same as the ones tsc gives.
npx tsc --noEmit2Fix
Fix the code at that line, or the type it is compared with. Ignoring a diagnostic by code is possible, but leave it for codes you understand.
// fix the type, not the check
const port: number = Number(process.env.PORT ?? 3000);3Verify
tsc passes, and ts-node starts.
npx tsc --noEmit
npx ts-node src/index.tsConfirmed by typestrong.org
Cause 2 of 4
Type declarations are not loaded
1Check
ts-node does not read files, include or exclude up front, so types that are only found that way can be missing at run time.
npx ts-node --showConfig | grep -i -E 'types|typeRoots|files|include'2Fix
Install the @types package for the library and, if you keep custom declarations, add their folder to typeRoots.
npm install --save-dev @types/node
// tsconfig.json
{ "compilerOptions": { "typeRoots": ["./node_modules/@types", "./typings"] } }3Verify
The missing name error no longer appears.
npx ts-node src/index.tsConfirmed by typestrong.org
Cause 3 of 4
ESM project run without the ESM loader
1Check
Native ESM needs a different entry point, and package.json type and tsconfig module must agree.
grep -n '"type"' package.json2Fix
Run with the ESM switch, or set esm in the ts-node section of tsconfig. Keep the whole project either CommonJS or ESM.
npx ts-node --esm src/index.ts
// or in tsconfig.json
{ "ts-node": { "esm": true } }3Verify
The file runs as a module.
npx ts-node --esm src/index.tsConfirmed by typestrong.org
Cause 4 of 4
You only need speed in development, and types are checked elsewhere
1Check
Transpile-only mode compiles each file alone and turns off type checking.
TS_NODE_TRANSPILE_ONLY=true npx ts-node src/index.ts2Fix
Use it for local runs only, and keep npx tsc --noEmit in CI so type errors still fail the pipeline.
// tsconfig.json
{ "ts-node": { "transpileOnly": true } }3Verify
The app starts, and the tsc check still passes.
npx tsc --noEmitConfirmed by typestrong.org
How do I stop it coming back?
- Run tsc --noEmit in CI so errors appear before runtime.
- Keep one module system per project and match tsconfig module with package.json type.
- Run ts-node --showConfig after changing tsconfig, to see what really applies.
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
TypeScript cannot find the type definition file for 'node'
The file is in the program because: Entry point of type library 'node' specified in compilerOptions
TS2688 means tsconfig asks for the 'node' type package, and TypeScript cannot find it where it looks.
2 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