{"record":{"id":"f21fa615a9d6a98a","repo":"abhigyanpatwari/GitNexus","slug":"worker-pool-failed-to-start-cause-failuredeta","errorCode":null,"errorMessage":"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}","messagePattern":"Worker pool failed to start: (.+?)(.+?)\\\\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  • (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts","lineNumber":424,"sourceCode":"  const cause =\n    crashClass === 'deterministic-startup'\n      ? `every worker crashed identically during startup (a deterministic ` +\n        `crash-loop — retrying cannot help), so the pool has no usable workers.`\n      : isInit\n        ? `workers exhausted the bounded startup retry budget without reporting ` +\n          `ready, so the pool has no usable workers.`\n        : `the worker pool could not be constructed.`;\n\n  // Class-aware fix hint: a missing/broken native binding is the likely cause\n  // when workers crashed during init, but it is the WRONG guess for a pool that\n  // never constructed (commonly a missing build / unresolvable worker path).\n  const fixHint = isInit\n    ? `Fix the worker startup failure shown above (often a missing/broken native ` +\n      `binding or a top-of-script import error in parse-worker).`\n    : `Fix the worker pool construction error shown above (commonly a missing ` +\n      `build, so dist/ has no parse-worker, or an unresolvable worker path).`;\n\n  throw new Error(\n    `Worker pool failed to start: ${cause}${failureDetail}\\n\\n` +\n      `The worker pool is GitNexus's only parse path — there is no sequential ` +\n      `fallback to hide this crash behind (silently degrading masked a ` +\n      `worker-startup regression as a 2-hour \"stuck\" run in #1741). Fix:\\n` +\n      `  • ${fixHint}`,\n  );\n}\n\n/**\n * Chunked parse + resolve loop.\n *\n * Reads source in byte-budget chunks (~20MB each):\n * 1. Parse each chunk via the worker pool (the sole parse path)\n * 2. After all chunks parse, emit route CALLS edges (deferred so resolution\n *    sees the full repo graph) and collect the exported-type map\n * 3. Collect TypeEnv bindings for cross-file propagation\n *\n * Import, call, and inheritance edges are emitted by the scope-resolution","sourceCodeStart":406,"sourceCodeEnd":442,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts#L406-L442","documentation":"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).","triggerScenarios":"(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.","commonSituations":"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.","solutions":["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.","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.","Do NOT retry analyze unchanged — this is a deterministic crash, identical retries are noise. Fix the underlying startup failure first.","Run `npm install` again if node_modules looks incomplete; reinstall optional grammars if a tree-sitter load is the readiness failure."],"exampleFix":"// before — analyze fails because dist/ has no parse-worker\n$ node .gitnexus/run.cjs analyze\n=> Error: Worker pool failed to start: ... dist/ has no parse-worker ...\n\n// after — build first, then analyze\n$ cd gitnexus && npm run build && cd ..\n$ node .gitnexus/run.cjs analyze","handlingStrategy":"try-catch","validationCode":"import * as fs from 'node:fs';\nimport * as path from 'node:path';\n// pre-flight: ensure the worker bundle exists before analyze\nfunction parseWorkerBundleExists(repoRoot: string): boolean {\n  const candidate = path.join(repoRoot, 'gitnexus', 'dist', 'pipeline-phases', 'parse-worker.js');\n  return fs.existsSync(candidate);\n}\nif (!parseWorkerBundleExists(repoRoot)) {\n  throw new Error('parse-worker bundle missing in dist/ — run `npm run build` in gitnexus/ first');\n}","typeGuard":null,"tryCatchPattern":"// handleWorkerStartupFailure is `never` — it always throws and there is no\n// recovery inside analyze. Catch at the top-level CLI to give the operator a\n// clean exit and avoid any temptation to retry unchanged.\ntry {\n  await runAnalyze(repo, options);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Worker pool failed to start:')) {\n    console.error(err.message); // already actionable\n    process.exitCode = 1;\n    return;\n  }\n  throw err;\n}","preventionTips":["Always run `npm run build` in gitnexus/ after install or after pulling changes that touch parse-worker.","Ensure the native toolchain (python3, make, g++) is present so tree-sitter grammars build, or set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 if optional grammars are the readiness failure.","Never retry analyze unchanged after this error — it is deterministic. Read the captured readinessFailures and fix the underlying worker crash first.","In CI, add a pre-flight check that dist/parse-worker.js exists before invoking analyze."],"tags":["worker-pool","parse","startup","build","native-binding","ingestion","fatal"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}