abhigyanpatwari/GitNexus · critical · Error

Worker pool failed to start: ${cause}${failureDetail}\n\nThe

Error message

Worker pool failed to start: ${cause}${failureDetail}\n\nThe worker pool is GitNexus's only parse path — there is no sequential fallback to hide this crash behind (silently degrading masked a worker-startup regression as a 2-hour "stuck" run in #1741). Fix:\n  • ${fixHint}

What it means

Thrown by handleWorkerStartupFailure (parse-impl.ts) — a function marked `never` that always throws. It is reached only after the worker pool's bounded self-heal is exhausted (every worker crashed identically, retries depleted, or the pool could not be constructed at all). GitNexus has NO sequential parse fallback — it was removed because silent degradation once masked a worker-startup regression as a 2-hour stuck run (#1741). So this throw deliberately aborts the analyze run to force the operator to fix worker startup. The message includes a class-aware fix hint distinguishing init crashes (native binding / import error) from construction failures (missing build / unresolvable worker path).

Source

Thrown at gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts:424

  const cause =
    crashClass === 'deterministic-startup'
      ? `every worker crashed identically during startup (a deterministic ` +
        `crash-loop — retrying cannot help), so the pool has no usable workers.`
      : isInit
        ? `workers exhausted the bounded startup retry budget without reporting ` +
          `ready, so the pool has no usable workers.`
        : `the worker pool could not be constructed.`;

  // Class-aware fix hint: a missing/broken native binding is the likely cause
  // when workers crashed during init, but it is the WRONG guess for a pool that
  // never constructed (commonly a missing build / unresolvable worker path).
  const fixHint = isInit
    ? `Fix the worker startup failure shown above (often a missing/broken native ` +
      `binding or a top-of-script import error in parse-worker).`
    : `Fix the worker pool construction error shown above (commonly a missing ` +
      `build, so dist/ has no parse-worker, or an unresolvable worker path).`;

  throw new Error(
    `Worker pool failed to start: ${cause}${failureDetail}\n\n` +
      `The worker pool is GitNexus's only parse path — there is no sequential ` +
      `fallback to hide this crash behind (silently degrading masked a ` +
      `worker-startup regression as a 2-hour "stuck" run in #1741). Fix:\n` +
      `  • ${fixHint}`,
  );
}

/**
 * Chunked parse + resolve loop.
 *
 * Reads source in byte-budget chunks (~20MB each):
 * 1. Parse each chunk via the worker pool (the sole parse path)
 * 2. After all chunks parse, emit route CALLS edges (deferred so resolution
 *    sees the full repo graph) and collect the exported-type map
 * 3. Collect TypeEnv bindings for cross-file propagation
 *
 * Import, call, and inheritance edges are emitted by the scope-resolution

View on GitHub (pinned to d540b00184)

Solutions

  1. If the message says 'the worker pool could not be constructed': run the build (e.g. `npm run build` in gitnexus/) so dist/ contains the parse-worker bundle, then retry.
  2. If the message says 'every worker crashed identically during startup': read the captured readinessFailures — they hold the real worker crash. A missing/broken native binding (tree-sitter) or a top-of-script import error in parse-worker is the usual cause. Install the required native toolchain (python3, make, g++) or set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 if an optional grammar is at fault.
  3. Do NOT retry analyze unchanged — this is a deterministic crash, identical retries are noise. Fix the underlying startup failure first.
  4. Run `npm install` again if node_modules looks incomplete; reinstall optional grammars if a tree-sitter load is the readiness failure.

Example fix

// before — analyze fails because dist/ has no parse-worker
$ node .gitnexus/run.cjs analyze
=> Error: Worker pool failed to start: ... dist/ has no parse-worker ...

// after — build first, then analyze
$ cd gitnexus && npm run build && cd ..
$ node .gitnexus/run.cjs analyze
Defensive patterns

Strategy: try-catch

Validate before calling

import * as fs from 'node:fs';
import * as path from 'node:path';
// pre-flight: ensure the worker bundle exists before analyze
function parseWorkerBundleExists(repoRoot: string): boolean {
  const candidate = path.join(repoRoot, 'gitnexus', 'dist', 'pipeline-phases', 'parse-worker.js');
  return fs.existsSync(candidate);
}
if (!parseWorkerBundleExists(repoRoot)) {
  throw new Error('parse-worker bundle missing in dist/ — run `npm run build` in gitnexus/ first');
}

Try / catch

// handleWorkerStartupFailure is `never` — it always throws and there is no
// recovery inside analyze. Catch at the top-level CLI to give the operator a
// clean exit and avoid any temptation to retry unchanged.
try {
  await runAnalyze(repo, options);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Worker pool failed to start:')) {
    console.error(err.message); // already actionable
    process.exitCode = 1;
    return;
  }
  throw err;
}

Prevention

When it happens

Trigger: (a) dist/ is missing the parse-worker bundle (build never ran or was cleaned); (b) a top-of-script import error in parse-worker crashes every worker on startup; (c) a missing or broken native binding (e.g. tree-sitter grammar load failure) crashes worker init deterministically; (d) the worker script path is unresolvable.

Common situations: Running analyze from source without building first (no dist/); a broken optional grammar (C/C++ toolchain missing) crashing worker init; a fresh checkout where `npm install && npm run build` wasn't completed; a corrupt node_modules; a TypeScript/import-path regression in parse-worker.ts.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/f21fa615a9d6a98a. Report an issue: GitHub.