Worker ${i} hit a deterministic startup crash-loop; dropping

Error message

Worker ${i} hit a deterministic startup crash-loop; dropping slot without further retries.

What it means

Parsing workers must post a ready message after spawn. When a worker dies before ready, the pool respawns the slot with jittered backoff, up to STARTUP_RESTART_BUDGET (2) attempts, while tracking each crash's startup signature. If the same signature reproduces across enough slots (deterministicSlotThreshold) before any worker ever reached ready, the pool classifies the failure as deterministic — every respawn would fail identically — and drops the slot(s) with this warning instead of looping forever. The pool continues with the surviving workers.

Source

Thrown at gitnexus/src/core/ingestion/workers/worker-pool.ts:1291

        const msg = err instanceof Error ? err.message : String(err);
        const sig = crashSignature(msg);
        // Same signature as this slot's previous attempt => it survived a
        // respawn, so retrying this slot is futile. (First crash has no prior
        // signature, so attempt 0 never counts — every slot self-heals once.)
        if (lastStartupSignature.get(i) === sig) reproducedStartupSlots.add(i);
        lastStartupSignature.set(i, sig);
        if (!anyWorkerReachedReady && reproducedStartupSlots.size >= deterministicSlotThreshold) {
          deterministicStartupDetected = true;
        }
        await worker.terminate().catch(() => undefined);
        workers[i] = undefined;

        const giveUp =
          terminated || deterministicStartupDetected || attempt >= STARTUP_RESTART_BUDGET;
        if (giveUp) {
          initialReadinessFailures.push(msg);
          activeSlots.delete(i);
          logger.warn(
            { workerIndex: i, attempt, err: msg, deterministic: deterministicStartupDetected },
            deterministicStartupDetected
              ? `Worker ${i} hit a deterministic startup crash-loop; dropping slot without further retries.`
              : `Worker ${i} did not report ready after ${attempt + 1} attempt(s); dropping slot.`,
          );
          return;
        }
        // Transient: jittered backoff, then respawn the slot and retry.
        await abortableSleep(
          startupBackoffMs(attempt),
          () => terminated || deterministicStartupDetected,
          pendingStartupTimers,
        );
        if (terminated || deterministicStartupDetected) {
          initialReadinessFailures.push(msg);
          activeSlots.delete(i);
          return;
        }

View on GitHub (pinned to 0d1aed942f)

Solutions

Read the { err } (msg) field — it carries the crash reason (e.g. 'was compiled against a different Node.js version')
Rebuild dependencies for the current runtime: rm -rf node_modules && npm install in gitnexus/ (postinstall re-materializes vendored grammars; a matching platform-arch prebuild is preferred, else a C/C++ toolchain source-builds them)
Pin or verify a supported Node.js version and reinstall after any major upgrade
Raise container memory/process limits if msg shows OOM or spawn failures
Re-run analyze — with all slots dropped the run loses worker parallelism, so fixing the environment is required

Example fix

# before: Node upgraded, native tree-sitter bindings have stale ABI, every worker crash-loops
node -v && npx gitnexus analyze  # -> deterministic startup crash-loop

# after: rebuild deps for the current Node, then re-index
cd gitnexus && rm -rf node_modules && npm install
cd .. && node .gitnexus/run.cjs analyze --index-only

Defensive patterns

Strategy: retry

Validate before calling

// preflight in the host: load native bindings the workers will load
try {
  require('web-tree-sitter');
  for (const g of ['tree-sitter-c', 'tree-sitter-kotlin', 'tree-sitter-swift']) require(g);
} catch (e) {
  failFast(`native grammar load failed - workers will crash-loop: ${e.message}`);
}

Prevention

After any Node.js major upgrade, rm -rf node_modules && npm install in gitnexus/ so native tree-sitter bindings match the runtime ABI
Verify a platform-arch prebuild exists (or a python3/make/g++ toolchain for the source-build fallback) before deploying
Give containers enough memory and process slots for N workers plus the host
Read the { err } msg in the warn — 'compiled against a different Node.js version' means ABI mismatch, not a GitNexus bug

When it happens

Trigger: Something that crashes every worker identically at boot: a missing or ABI-incompatible native tree-sitter binding (Node upgraded without rebuilding node_modules), a corrupted or partial npm install, a broken worker bundle path, or container limits OOM-killing workers while grammars load.

Common situations: Upgrading Node.js without reinstalling gitnexus deps (NODE_MODULE_VERSION mismatch); interrupted installs leaving half-written native .node files; Docker/CI with tight memory or max-process limits; antivirus quarantining native binaries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-08-20). Data as JSON: /api/errors/cce3bd62682e25d0. Report an issue: GitHub.