Production worker exits with code 2 right after boot

Symptom

The built service (node dist/index.js) starts, prints one line from a module that has nothing to do with startup, and exits:

collect: COLLECTOR_KEY is required
exit 2

In a container this is a restart loop (Restarting (2), Kubernetes CrashLoopBackOff with exit code 2). With the env var present it is worse: the process runs the command-line tool's job (in our case "run every collector once") and then exits 0 or keeps doing the wrong work. Development (tsx src/index.ts, ts-node, plain node src/...) works perfectly, so nothing shows until the bundled artifact runs.

When it happens

A module that is both a library and a CLI decides "was I run directly?" with the common ESM idiom:

import { pathToFileURL } from 'node:url'
if (import.meta.url === pathToFileURL(process.argv[1]).href) {
  // CLI mode
}

…and the service is bundled into one file (esbuild --bundle --format=esm, same for other bundlers that inline ESM modules), with that module imported by the entry point. Also affected: the newer import.meta.main (Node 24.21.0 tested): inside a bundle it is true in the inlined module too.

Cause

import.meta.url is per file at runtime, not per source module. After bundling, the CLI module's code lives in dist/index.js; there, import.meta.url is file:///app/dist/index.js, and process.argv[1] is /app/dist/index.js — equal. The check that was correct for src/collect.ts is now true in the main service. esbuild leaves the expression as is (grep -n import.meta.url dist/index.js shows it inlined); this is not a bug in esbuild, the idiom simply does not survive bundling.

Fix

Decide by the entry file's name, which survives bundling:

// cli.ts
export function isCli (name: string): boolean {
  const entry = process.argv[1] ?? ''
  return new RegExp(`(^|[\\\\/])${name}\\.(ts|js|mjs)$`).test(entry)
}

// collect.ts
import { isCli } from './cli.js'
if (isCli('collect')) { /* CLI mode */ }

Then:

• node dist/index.js → isCli('collect') is false (entry is index.js), the worker runs.
• node dist/collect.js all (build the CLI as its own entry point) and tsx src/collect.ts all → true.

Other workable options: move CLI code into separate entry files that only import the library (cleanest), or gate CLI mode on an explicit env var/flag.

Verify

Boot the built artifact in CI and require it to stay up:

npm run build
node dist/index.js & pid=$!
sleep 15
kill -0 "$pid" && echo "worker alive after 15 s" || { echo "worker died"; exit 1; }
kill "$pid"

In Kubernetes, assert the pod's restartCount is 0 after install. Reproduction result on 2026-09-30:

--- dev: npx tsx src/index.ts        -> worker started … alive after 3 s, exit 0
--- prod: node dist/index.js         -> collect: COLLECTOR_KEY is required, exit 2
--- fixed prod: node dist/index.js   -> worker started … alive after 3 s, exit 0
--- fixed CLI: node dist/collect.js x -> collected x, exit 0

Notes (what did not help)

• Unit and integration tests all ran against sources under tsx and passed; only a boot test of the built output catches it. We found it while installing a Helm chart on a local kind cluster.
• import.meta.main (tested on Node 24.21.0) has the same problem once bundled: the bundle is the main module.
• Comparing fileURLToPath(import.meta.url) with process.argv[1] is the same check in another spelling and fails the same way. (CommonJS require.main === module was not tested.)
• If the package is not "type": "module", tsx fails earlier with Top-level await is currently not supported with the "cjs" output format — unrelated, but it can mask this when you try to reproduce.
• Also check other side effects at module top level (opening DB pools, ending them): in our case a second CLI module would have closed the shared database pool of the running worker.