Maaz Zindani

Loading the index…

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

ts-node stops with 'TSError: ⨯ Unable to compile TypeScript'

ErrorTSError: ⨯ 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.

  • 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

    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 --showConfig
  2. 2Match what you see, then jump to its fix

    1. 1file(line,col): error TSxxxx right under the TSError lineA real type error in the file named in the messageFix
    2. 2Cannot find name 'process' or Cannot find module, though the package is installedType declarations are not loadedFix
    3. 3ERR_UNKNOWN_FILE_EXTENSION or ERR_REQUIRE_ESMESM project run without the ESM loaderFix
    4. 4Large project, slow start, and the type check already runs in the editor or CIYou only need speed in development, and types are checked elsewhereFix

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 --noEmit

2Fix

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.ts

Confirmed by typestrong.org

Did this fix it?

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.ts

Confirmed by typestrong.org

Did this fix it?

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.json

2Fix

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.ts

Confirmed by typestrong.org

Did this fix it?

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.ts

2Fix

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 --noEmit

Confirmed by typestrong.org

Did this fix it?

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:

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 fix

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.