{"record":{"id":"2be48aba0a56d81f","repo":"abhigyanpatwari/GitNexus","slug":"worker-pool-parsing-cannot-be-disabled-reason","errorCode":null,"errorMessage":"Worker-pool parsing cannot be disabled (${reason}). GitNexus no longer has a sequential parser — the worker pool self-heals via quarantine + respawn, so there is no slower path to fall back to. Pass `--workers <N>` with N>=1, or omit it for an auto-sized pool.","messagePattern":"Worker-pool parsing cannot be disabled \\((.+?)\\)\\. GitNexus no longer has a sequential parser — the worker pool self-heals via quarantine \\+ respawn, so there is no slower path to fall back to\\. Pass `--workers <N>` with N>=1, or omit it for an auto-sized pool\\.","errorType":"exception","errorClass":"WorkerPoolDisabledError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts","lineNumber":553,"sourceCode":"    });\n  }\n\n  // Sequential parsing has been removed: the worker pool (quarantine +\n  // respawn/recycle + circuit breaker) is the sole parse path. The three\n  // channels that used to select an in-process parser are now hard errors, so\n  // an operator who set one gets an actionable message instead of a silently\n  // slower (now nonexistent) fallback. Validated before any chunk work; a\n  // zero-parseable-file repo is exempt (nothing to parse).\n  if (totalParseable > 0) {\n    const requestedPoolSize = options?.workerPoolSize;\n    const disabledByEnv = requestedPoolSize === undefined && workerPoolDisabledByEnv();\n    if (options?.skipWorkers || requestedPoolSize === 0 || disabledByEnv) {\n      const reason = options?.skipWorkers\n        ? '`skipWorkers: true` was passed'\n        : requestedPoolSize === 0\n          ? '`--workers 0` (workerPoolSize=0) was requested'\n          : '`GITNEXUS_WORKER_POOL_SIZE=0` is set';\n      throw new WorkerPoolDisabledError(\n        `Worker-pool parsing cannot be disabled (${reason}). GitNexus no longer ` +\n          `has a sequential parser — the worker pool self-heals via quarantine + ` +\n          `respawn, so there is no slower path to fall back to. Pass ` +\n          `\\`--workers <N>\\` with N>=1, or omit it for an auto-sized pool.`,\n      );\n    }\n  }\n\n  // Build byte-budget chunks. The budget is resolved per-call (U14): options\n  // first, then env, then the built-in default. Pre-U14 this was a\n  // module-load IIFE constant, which froze the env value at import time\n  // and made `PipelineOptions.chunkByteBudget` silently no-op on warm test\n  // runs. Resolving in the function body restores per-call configurability\n  // and matches the pattern used by resolveAutoPoolSize and the U1\n  // parseChunkConcurrency resolver.\n  // Effective worker count, computed up-front so the chunk budget can scale to\n  // keep the whole pool busy (#worker-idle). The pool is ALWAYS used (sequential\n  // parsing was removed; the disabled channels threw above). Size it to the","sourceCodeStart":535,"sourceCodeEnd":571,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts#L535-L571","documentation":"Thrown by the parse phase when the worker pool is explicitly disabled. GitNexus removed its sequential (in-process) parser, so the worker pool — with quarantine, respawn, and a circuit breaker — is the ONLY parse path. There is no slower fallback to silently degrade to, so the three legacy disable channels (`skipWorkers: true`, `--workers 0`/`workerPoolSize=0`, and `GITNEXUS_WORKER_POOL_SIZE=0`) are now hard configuration errors instead of feature switches. The check only fires when there are parseable files; a repo with zero parseable files is exempt.","triggerScenarios":"Calling `analyze`/`processParsing` with `PipelineOptions.skipWorkers = true`; passing `--workers 0` on the CLI (workerPoolSize=0); or having `GITNEXUS_WORKER_POOL_SIZE=0` set in the environment while no explicit positive `workerPoolSize` is passed — all only when `totalParseable > 0`.","commonSituations":"An operator who read old docs sets `GITNEXUS_WORKER_POOL_SIZE=0` to debug single-threaded parsing (that path no longer exists). A CI script pins `--workers 0` to reduce memory. A test harness passes `skipWorkers: true` expecting the legacy in-process fallback. An upgrade from an older GitNexus version leaves the now-invalid env var exported in a shell profile.","solutions":["Pass `--workers <N>` with N>=1, or omit `--workers` entirely so the pool auto-sizes to `os.availableParallelism() - 1` (clamped to the cap).","Unset `GITNEXUS_WORKER_POOL_SIZE` from the environment (check `.env`, CI config, shell profiles) if you did not set it explicitly.","Remove `skipWorkers: true` from the `PipelineOptions` object you pass to the analyze API.","If you genuinely need single-worker parsing for debugging, pass `--workers 1` rather than disabling the pool."],"exampleFix":"// before\nconst options = { skipWorkers: true };\nawait analyze(repo, options); // throws WorkerPoolDisabledError\n\n// after — let the pool auto-size\nconst options = {};\nawait analyze(repo, options);\n\n// or pin to a single worker for debugging\nconst options = { workerPoolSize: 1 };","handlingStrategy":"validation","validationCode":"// Before calling analyze, validate the worker-pool config\nimport { workerPoolDisabledByEnv } from 'gitnexus/dist/core/ingestion/workers/worker-pool.js';\n\nfunction assertWorkerPoolUsable(options) {\n  if (options?.skipWorkers) {\n    throw new Error('Refusing to analyze: skipWorkers is set but the worker pool is the only parser.');\n  }\n  if (options?.workerPoolSize === 0) {\n    throw new Error('Refusing to analyze: workerPoolSize=0 is not allowed.');\n  }\n  if (options?.workerPoolSize === undefined && workerPoolDisabledByEnv()) {\n    throw new Error('Refusing to analyze: GITNEXUS_WORKER_POOL_SIZE=0 is set in the environment.');\n  }\n}\n\nassertWorkerPoolUsable(options);\nawait analyze(repo, options);","typeGuard":"// Narrow PipelineOptions to ensure the pool is not disabled\ntype WorkerPoolSafeOptions = {\n  skipWorkers?: false;\n  workerPoolSize?: number; // must be >= 1\n};\nfunction isWorkerPoolSafe(o): o is WorkerPoolSafeOptions {\n  return o.skipWorkers !== true && o.workerPoolSize !== 0;\n}","tryCatchPattern":"try {\n  await analyze(repo, options);\n} catch (err) {\n  if (err.name === 'WorkerPoolDisabledError') {\n    // config error — fix the flag/env and re-run, do not retry as-is\n    console.error(err.message);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["Never set GITNEXUS_WORKER_POOL_SIZE=0 in CI/shell profiles — it is a legacy switch that no longer works.","Audit PipelineOptions before calling analyze; treat skipWorkers/workerPoolSize=0 as programmer errors.","When upgrading GitNexus, grep your environment and scripts for removed worker-pool disable flags."],"tags":["worker-pool","configuration","parsing","env-var","migration"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}