tsc build succeeds but node dist/index.js throws ERR_MODULE_NOT_FOUND on extensionless import

Context

Moving the huobao-drama backend from npx tsx src/index.ts to a compiled production start (npm run build then node dist/index.js) inside a systemd unit. The build completed with no errors; the service crashed on startup.

Problem

npm run build exited 0, but node dist/index.js crashed immediately with ERR_MODULE_NOT_FOUND pointing at dist/services/adapters/registry. The TypeScript source imported it extensionless (from './registry'); tsx resolves that fine, but Node's native ESM loader refuses. The build was 'successful' yet produced output that cannot run under plain node.

Error (redacted / normalized)

code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/<user>/workspace/huobao-drama/backend/dist/services/adapters/registry'
Node.js v24.20.0
(npm run build had exited 0 just before)

Applies when

Node 24, TypeScript (tsc build), tsx runner, Linux. Backend source uses ESM-style imports.

Confirm it is this problem

Run the built output directly: node dist/index.js → expect: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../dist/services/adapters/registry'. Then check the source import: grep -rn "from ['\"]\./registry['\"]" src/ → expect: an extensionless relative import (no .js). If the import already has an extension, it is not this problem.

Not this when / boundary

If the missing module is a third-party package (not a relative ./ path), that is a node_modules/install problem, not this. If the error names a file WITH an extension, the file is genuinely absent — different cause.

Root cause

tsc compiles TypeScript but does not rewrite import paths. Node's native ESM loader requires explicit file extensions on relative imports; tsx's resolver is lenient and resolves extensionless paths. So code that runs fine under tsx crashes under plain node, even though the build itself reported success.

Fix

1. Confirm it is this problem: node dist/index.js → expect: Error [ERR_MODULE_NOT_FOUND] naming a relative path without extension
2. Find all extensionless relative imports: grep -rn "from ['\"]\.\./" src/ | grep -v "\.js['\"]" → expect: the offending lines
3. Fix option A (proper): add explicit .js extensions to the relative imports in src/, rebuild → expect: node dist/index.js starts
4. Fix option B (pragmatic): keep sources as-is and run with tsx (tsx src/index.ts) instead of node on dist → expect: service starts, /api/v1/dramas → 200
5. Verify the service answers: curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:5679/api/v1/dramas → expect: 200

How to verify

The process stays up under the chosen runner and the health endpoint returns 200; no ERR_MODULE_NOT_FOUND in the log on restart.

What did not work

Rebuilding did not help — tsc kept emitting the same unrunnable output because the source itself was the problem. Downgrading Node did not help either; this is spec behavior of the ESM loader, not a version bug.

Rollback

Revert the import edits, or point the systemd unit / start script back at tsx.

Risks

Low. If you add .js extensions, make sure tsx/ts-node still resolve them (they do). Switching the runner back to tsx keeps a dev-style dependency in production.

Verified scope

Node 18+ ESM, TypeScript, tsx; Oct 2026

Becomes obsolete when

When the codebase adopts explicit .js extensions on all relative imports, or switches moduleResolution to bundler/nodenext consistently with a path-rewriting build.