Node ERR_UNKNOWN_FILE_EXTENSION ".ts" in CI - Run TypeScript Correctly

By Daniel Zoghalchali·Latchkey

ERR_UNKNOWN_FILE_EXTENSION means you asked node to execute a .ts file directly, but the plain Node runtime has no loader registered for TypeScript.

What this error means

A CI step runs node src/index.ts and throws TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts". It works locally where a TS loader is wired up.

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"
for /home/runner/work/app/app/src/index.ts
    at Object.getFileProtocolModuleFormat (node:internal/modules/esm/load:101:9)

Common causes

Running .ts files with plain node

Stock Node has no TypeScript loader on older versions, so it cannot determine a module format for .ts.

A missing loader registration

The tsx or ts-node loader is registered via a flag or NODE_OPTIONS locally but not in the CI command.

How to fix it

Run TypeScript with tsx

1. Invoke the file through tsx, which registers a TypeScript loader.
2. Use the same command locally and in CI.

- run: npx tsx src/index.ts

Compile first, then run the JavaScript

1. Add a tsc build step to emit .js.
2. Execute the compiled output with node.

- run: npx tsc -p tsconfig.json
- run: node dist/index.js

How to prevent it

• Standardize on one TypeScript execution path (tsx, ts-node, or compiled output) and use it identically across local dev and CI so the loader is always present.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation