abhigyanpatwari/GitNexus · critical

Worker pool failed to start

Error message

Worker pool failed to start: ${cause}${failureDetail}

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:
  • ${fixHint}

What it means

Thrown in gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts when the parse worker pool cannot be constructed or its workers crash during init. The worker pool is GitNexus's ONLY parse path — the sequential parser was removed (a silent fallback masked a startup regression as a 2-hour 'stuck' run, #1741), so the failure is fatal and loud. The message branches on isInit: init crashes point at a missing/broken native binding or a top-of-script import error in parse-worker; construction failures point at a missing build (no dist/ parse-worker) or unresolvable worker path.

Solutions

  1. Rebuild the package so dist/ contains the parse-worker (e.g. `npm run build` in gitnexus/ or reinstall the CLI)
  2. If the message says workers crashed during init, fix the native binding: reinstall dependencies so tree-sitter grammars rebuild (`npm install`, or use GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 if a toolchain is unavailable)
  3. Verify the parse-worker file exists at the path the pool resolves and that importing it standalone raises no error (`node -e "import('<worker path>')"`)
  4. Check the underlying error printed above the throw for the specific import or binding that failed

Example fix

# before: stale checkout, no build products
$ node bin/gitnexus analyze .
# after
$ npm install && npm run build
$ node bin/gitnexus analyze .
Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'node:fs';
// Pre-flight when driving analyze programmatically: the worker bundle must exist
const workerPath = path.join(packageRoot, 'dist', 'core', 'ingestion', 'workers', 'parse-worker.js');
if (!fs.existsSync(workerPath)) {
  throw new Error('Parse worker bundle missing — run `npm run build` / reinstall gitnexus before analyze');
}

Try / catch

try {
  await runAnalyze(repoPath, options);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Worker pool failed to start')) {
    // Distinguish the two hints in the message: init crash -> reinstall native deps;
    // construction failure -> rebuild dist. Fail the pipeline loudly; never retry unchanged.
  }
  throw err;
}

Prevention

When it happens

Trigger: Running analyze (a) from a source checkout without a build, so dist/ has no parse-worker JS; (b) after the worker file was moved/renamed so its path no longer resolves; (c) with a broken tree-sitter native binding in node_modules so workers die during init; (d) with a top-of-script import error inside parse-worker (bad export, missing optional dependency).

Common situations: Pulling latest changes and running the CLI without rebuilding; a partial or interrupted `npm install` leaving native grammars half-built; packaging the CLI without shipping the worker bundle; node version change invalidating prebuilt native bindings.

Related errors

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

Appendix: source

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

  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 ac9a4e9abd)