Worker ${i} crashed during startup; respawning slot (self-he

Error message

Worker ${i} crashed during startup; respawning slot (self-heal attempt ${attempt + 1}/${STARTUP_RESTART_BUDGET}).

What it means

Each pool slot runs a bounded startup retry loop: if a worker's readiness fails (crash during startup), the slot backs off with jitter (abortable on termination or deterministic-failure detection) and respawns, up to STARTUP_RESTART_BUDGET (2) self-heal attempts. This warn announces each respawn; unrecoverable slots are recorded in initialReadinessFailures and dropped before the first dispatch.

Source

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

            { 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;
        }
        logger.warn(
          { workerIndex: i, attempt: attempt + 1 },
          `Worker ${i} crashed during startup; respawning slot (self-heal attempt ${attempt + 1}/${STARTUP_RESTART_BUDGET}).`,
        );
        workers[i] = spawnAndCapture(workerUrl);
      }
    }
  };

  // First dispatch awaits this; it settles every slot's bounded retry loop in
  // parallel and drops the unrecoverable ones before any dispatch can fire.
  const initialReadyGate: Promise<void> = Promise.allSettled(
    workers.map((_, i) => bringSlotReady(i)),
  ).then(() => undefined);

  /**
   * Guards the one-dispatch-at-a-time contract. The dispatch machinery keeps
   * its jobs/busy-slot/in-flight state per call, so two concurrent dispatches
   * hand the same slots out twice: both stall, and the failure surfaces only

View on GitHub (pinned to 0d1aed942f)

Solutions

Check the worker's stderr/first-failure message (collected into initialReadinessFailures) to identify whether the crash is native-load, OOM, or transient
Verify the install: matching prebuilt grammar binaries, or a C/C++ toolchain (python3, make, g++) present when source-building; consider GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 for optional languages
Reduce boot memory pressure: lower GITNEXUS_WORKER_POOL_SIZE / GITNEXUS_WORKER_HEAP_MB per the overcommit guidance
If failures are deterministic, the slot is dropped automatically — read the surfaced readiness error rather than retrying blindly

Example fix

# before
npm install   # optional grammar source-build mismatch → worker crashes at startup
# after
export GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1
npm install && npx gitnexus analyze   # optional grammars skipped, startup clean

Defensive patterns

Strategy: retry

Validate before calling

// De-risk startup before invoking analyze:
const missing = ['python3', 'make', 'g++'].filter((t) => !hasTool(t));
if (missing.length > 0) process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS = '1';
if (!process.env.GITNEXUS_WORKER_POOL_SIZE) {
  process.env.GITNEXUS_WORKER_POOL_SIZE = String(Math.min(4, os.cpus().length));
}

Prevention

Pin one CLI version for install and run so native grammar binaries match
Free boot memory pressure: smaller pool/heap on constrained containers
If readiness failures are deterministic, read the surfaced failure message instead of relying on the 2-attempt self-heal

When it happens

Trigger: Worker thread crashing before its readiness handshake — native grammar loading failure, OOM at boot, ABI-incompatible tree-sitter native module, or transient resource pressure; the loop logs the respawn attempt and re-spawns via spawnAndCapture.

Common situations: Fresh installs where optional vendored grammars got source-built against a mismatched toolchain, containers with tight memory at boot, transient cgroup/OOM pressure on CI, or flaky worker script loading under heavy FS contention.

Related errors

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