{"record":{"id":"b8bf70e16202b554","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":null,"httpStatus":null,"severity":"critical","filePath":"gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts","lineNumber":447,"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":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts#L429-L465","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Rebuild the package so dist/ contains the parse-worker (e.g. `npm run build` in gitnexus/ or reinstall the CLI)","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)","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>')\"`)","Check the underlying error printed above the throw for the specific import or binding that failed"],"exampleFix":"# before: stale checkout, no build products\n$ node bin/gitnexus analyze .\n# after\n$ npm install && npm run build\n$ node bin/gitnexus analyze .","handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs';\n// Pre-flight when driving analyze programmatically: the worker bundle must exist\nconst workerPath = path.join(packageRoot, 'dist', 'core', 'ingestion', 'workers', 'parse-worker.js');\nif (!fs.existsSync(workerPath)) {\n  throw new Error('Parse worker bundle missing — run `npm run build` / reinstall gitnexus before analyze');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runAnalyze(repoPath, options);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Worker pool failed to start')) {\n    // Distinguish the two hints in the message: init crash -> reinstall native deps;\n    // construction failure -> rebuild dist. Fail the pipeline loudly; never retry unchanged.\n  }\n  throw err;\n}","preventionTips":["Always rebuild (`npm run build`) after pulling source changes before running the CLI","Treat partial npm installs as suspect: reinstall when tree-sitter native modules fail to load anywhere else","Do not catch-and-continue this error in automation — there is no fallback parse path; surface it and fix the environment"],"tags":["workers","parse","native-binding","build","thread-pool","analyze"],"backgroundTag":"worker-thread-startup-failure","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}