# Fix "TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"" in ts-node

Yes. An agent finds why ts-node cannot load .ts files in an ES module package, changes the script to a loader that works on your Node version, and runs it.

[Run this on Rush](https://cloud.getrush.ai/run/fix-unknown-file-extension-ts/ts-node/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The error comes from Node, not from TypeScript. When `package.json` says `"type": "module"`, Node loads every file in the package through its ES module loader. The plain `ts-node` command only hooks the CommonJS loader, so the ES module loader meets `src/index.ts`, has no handler for the extension, and stops with `TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts"`. Nothing in the source file is wrong. Deleting `"type": "module"` makes the message go away and breaks every `import` that relies on ES module resolution, which is why the fix belongs in the script.

BangyiZhang/xmind-generator-mcp, an MCP server that writes XMind mind maps, has this exact setup. Its `package.json` declares `"type": "module"` and a `dev` script of `ts-node src/index.ts`, with ts-node 10.9.2 in the lockfile, and `tsconfig.json` sets both `module` and `moduleResolution` to `Node16`. The other two scripts work: `build` runs `tsc` and `start` runs `node dist/index.js`, which is also the path `setup.sh` and the README describe. Only `npm run dev` goes through ts-node. On Node 20.20 it stops with the error in the title before the first line of `src/index.ts` executes.

The agent installs from the lockfile, runs every script that mentions ts-node, and records which Node version produced which message, because the answer depends on it. On Node 20.20, `ts-node --esm src/index.ts`, the flag most answers suggest, fails with the same error, while `node --loader ts-node/esm src/index.ts` starts the server and prints a warning that `--loader` is experimental. On Node 22.23 the title's error is gone and a different one takes its place: Node strips the types from `index.ts` by itself and then cannot resolve the import on line 11, `./read.js`, which exists only as `read.ts`: `ERR_MODULE_NOT_FOUND`. A fix that was only tried on one Node version can leave the script broken on the other.

So the agent picks the change from what it observes on the versions the project supports (`engines` says Node 18 or later here). The candidates are the `--loader ts-node/esm` form, the `--import` form with `register()` that Node's warning recommends, or replacing ts-node in the script with `tsx`, which starts this server on both Node 20.20 and Node 22.23. It runs the chosen command on each version, holds stdin open because this server speaks MCP over stdio, checks that the process stays up and answers an `initialize` request, and confirms that `npm run build` followed by `npm start` behaves as before.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A script in this repository fails with: TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".ts\". Read package.json and report the \"type\" field, the engines field, every script that calls ts-node (or ts-node-dev, or nodemon with ts-node), and the ts-node and typescript versions in the lockfile. Read tsconfig.json and report module, moduleResolution and any \"ts-node\" block. Install dependencies from the lockfile and run each of those scripts; save the full error and the Node version that produced it. Then repeat on every Node major version the engines field or the CI matrix allows, installing each with a version manager, because newer Node releases load .ts files differently and the error text changes. Do not remove \"type\": \"module\" and do not rename source files to .cts or .mts. Fix the scripts instead: try ts-node --esm, node --loader ts-node/esm, node --import with register(), and tsx, and keep the one that starts cleanly on every supported Node version with the fewest new dependencies. If relative imports use .js specifiers for .ts files, make sure the chosen command resolves them. If the entry point is a long-running server, start it with stdin held open, confirm it stays up for ten seconds and answers one request, then stop it. Run the build and the test script before and after and report any difference. Open a pull request whose description has a table of command, Node version and result for everything you tried, and says which Node versions you could not test.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that usually changes one line of `package.json`, the script that called ts-node, plus `package-lock.json` when a runner such as `tsx` is added to `devDependencies`. If the README or a setup script quotes the old command, those lines change with it. No source file under `src` is touched, and `"type": "module"` stays where it is.

The description carries the table that makes the choice reviewable: each command the agent tried, the Node version it ran on, and whether it started, with the error text where it did not. A reviewer checks that the row for the Node version their team and their CI use says the script starts, and that the kept command does not print an experimental warning on every start unless the description says why that was accepted.

Before merging, the reviewer also reads what was not tested. A version the sandbox could not install is listed as untested, not assumed. If the agent replaced ts-node, the description says whether ts-node is still needed elsewhere, for example by a `ts-node` block in `tsconfig.json` or a test runner preset, before it is removed from `devDependencies`.

## Run it on every failed workflow run

This error tends to appear the day a Node version moves: a new base image, a bumped `.nvmrc`, a CI runner that changed its default. Give the Project an automation with a `github` trigger on `workflow_run.failure` and a prompt that tells the agent to read the failed job's log, and to act only when the log contains `ERR_UNKNOWN_FILE_EXTENSION` or a module-not-found error for a `.js` specifier next to a `.ts` file. The event is added after the prompt as text, and a workflow run from a fork never fires the trigger.

An automation's runs count against its own `max_runs_per_hour`, so a morning of failed pushes after a base image change is spread out: a run past the cap is created queued and starts when the hour has room. For a set of repositories that share one scaffold, send the request above once per repository from a script with an API key. Each run gets its own sandbox, and runs past the key's `max_concurrent` wait as `queued` until a slot frees.

## Why run it on Rush?

The right answer here is a function of the Node version, and most laptops have exactly one. The same `ts-node src/index.ts` gives the title's error on Node 20.20 and a module-not-found error on Node 22.23, and a flag that is recommended everywhere fails on one of them. In a sandbox the agent installs each Node version side by side, runs every candidate command on each, and keeps the output in the session, so the pull request rests on an observed table and not on an answer written for a different release.

It is also a fix that fails quietly when it is half done. A dev script is not part of the build, so CI stays green whether it works or not, and the next person to run it finds out. Because the run ends with the command started and answering, with the transcript of that start kept beside the diff, the reviewer does not have to check out the branch to know the script works.

## Frequently asked questions

### Why does ts-node --esm still fail with the same error?

Because the flag does not take effect on every Node release. In a check on Node 20.20 with ts-node 10.9.2, `ts-node --esm src/index.ts` failed with the same unknown-extension error, while `node --loader ts-node/esm src/index.ts` started the same file. The agent tests both forms on your Node version and does not assume either.

### Can I just remove "type": "module" from package.json?

Only if the code is CommonJS at heart. In a package written as ES modules, with `import.meta.url`, top-level `await` or `.js` specifiers in relative imports, removing the field trades this error for a list of others. The request above tells the agent to leave the field alone and fix the script.

### Does Node 22 fix this without any change?

It changes the error. Node 22.23 strips types from the entry file by itself, so the unknown-extension message does not appear, but an import written as `./read.js` for a file named `read.ts` then fails with `ERR_MODULE_NOT_FOUND`. A project whose imports use `.js` specifiers still needs a loader or a runner that maps them.

### Should I switch from ts-node to tsx?

It is one of the candidates, and for a dev script it is often the smallest change: one new dev dependency and one edited line. tsx does not type-check while it runs, so keep `tsc --noEmit` or the build in CI if ts-node was your only type check. The agent reports whether anything else in the repository still depends on ts-node before proposing its removal.

## More ts-node jobs

- [Replace ts-node With tsx in an Express and TypeDI API](https://getrush.ai/run/migrate-ts-node-to-tsx/ts-node/)

## More jobs like this: Fix a bug from an alert

- [Fix "deprecated version of actions/upload-artifact: v3" Workflow Failures](https://getrush.ai/run/fix-upload-artifact-v3-deprecation/github-actions/)
- [Fix `undefined method 'escape' for module URI` (NoMethodError) on Ruby 3](https://getrush.ai/run/fix-uri-escape-nomethoderror/uri/)
- [Fix "[DEP0169] DeprecationWarning: url.parse() behavior is not standardized"](https://getrush.ai/run/fix-url-parse-deprecation-warning/nodejs/)
- [Fix "Retry.__init__() got an unexpected keyword argument 'method_whitelist'"](https://getrush.ai/run/fix-urllib3-method-whitelist-error/urllib3/)
- [Fix "[DEP0060] DeprecationWarning: The util._extend API is deprecated" From http-proxy on Node 22](https://getrush.ai/run/fix-util-extend-deprecation-warning/http-proxy/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
