abhigyanpatwari/GitNexus · error · WorkerPoolDisabledError

Worker-pool parsing cannot be disabled

Error message

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.

What it means

WorkerPoolDisabledError from parse-impl.ts (line 557 area): analyze refuses to run when worker-pool parsing is explicitly disabled while the repo has parseable files. The sequential parser no longer exists — the pool self-heals via quarantine + respawn — so there is no slower path to fall back to. The three disabling triggers are skipWorkers: true, workerPoolSize: 0 (--workers 0), and GITNEXUS_WORKER_POOL_SIZE=0. A repo with zero parseable files is exempt.

Solutions

Run with `--workers <N>` where N >= 1, or omit the flag entirely for an auto-sized pool
Unset GITNEXUS_WORKER_POOL_SIZE (or set it to a positive value) in your shell profile, CI environment, or .env
Remove `skipWorkers: true` / `workerPoolSize: 0` from programmatic PipelineOptions calls

Example fix

# before
$ GITNEXUS_WORKER_POOL_SIZE=0 gitnexus analyze .
# after
$ unset GITNEXUS_WORKER_POOL_SIZE
gitnexus analyze . --workers 4

Defensive patterns

Strategy: validation

Validate before calling

const disabledByEnv =
  process.env.GITNEXUS_WORKER_POOL_SIZE !== undefined &&
  Number(process.env.GITNEXUS_WORKER_POOL_SIZE) === 0;
if (disabledByEnv || pipelineOptions?.skipWorkers || pipelineOptions?.workerPoolSize === 0) {
  delete process.env.GITNEXUS_WORKER_POOL_SIZE;
  pipelineOptions = { ...pipelineOptions, skipWorkers: undefined, workerPoolSize: undefined };
}
await runAnalyze(repoPath, pipelineOptions);

Try / catch

import { WorkerPoolDisabledError } from './core/ingestion/workers/worker-pool.js';
try {
  await runAnalyze(repo, opts);
} catch (err) {
  if (err instanceof WorkerPoolDisabledError) {
    // config error, not transient: strip skipWorkers / zero pool size and re-run once
  }
  throw err;
}

Prevention

Purge GITNEXUS_WORKER_POOL_SIZE=0 from shell profiles, CI variables, and .env files after upgrading GitNexus
Update tests and scripts that pass skipWorkers: true — the sequential parser no longer exists
To shrink resource use, pass --workers 1, never --workers 0

When it happens

Trigger: Running `gitnexus analyze --workers 0`; exporting GITNEXUS_WORKER_POOL_SIZE=0 in the environment; programmatic pipeline calls passing options.skipWorkers = true or options.workerPoolSize = 0 — all on a repo containing at least one parseable file.

Common situations: Upgrading from an older GitNexus version where disabling workers was allowed (legacy env var left in .bashrc/CI env); developers setting --workers 0 while debugging worker issues; test suites still passing skipWorkers; CI images baking in the old env var.

Related errors

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

Appendix: source

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

    });
  }

  // Sequential parsing has been removed: the worker pool (quarantine +
  // respawn/recycle + circuit breaker) is the sole parse path. The three
  // channels that used to select an in-process parser are now hard errors, so
  // an operator who set one gets an actionable message instead of a silently
  // slower (now nonexistent) fallback. Validated before any chunk work; a
  // zero-parseable-file repo is exempt (nothing to parse).
  if (totalParseable > 0) {
    const requestedPoolSize = options?.workerPoolSize;
    const disabledByEnv = requestedPoolSize === undefined && workerPoolDisabledByEnv();
    if (options?.skipWorkers || requestedPoolSize === 0 || disabledByEnv) {
      const reason = options?.skipWorkers
        ? '`skipWorkers: true` was passed'
        : requestedPoolSize === 0
          ? '`--workers 0` (workerPoolSize=0) was requested'
          : '`GITNEXUS_WORKER_POOL_SIZE=0` is set';
      throw new WorkerPoolDisabledError(
        `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.`,
      );
    }
  }

  // Build byte-budget chunks. The budget is resolved per-call (U14): options
  // first, then env, then the built-in default. Pre-U14 this was a
  // module-load IIFE constant, which froze the env value at import time
  // and made `PipelineOptions.chunkByteBudget` silently no-op on warm test
  // runs. Resolving in the function body restores per-call configurability
  // and matches the pattern used by resolveAutoPoolSize and the U1
  // parseChunkConcurrency resolver.
  // Effective worker count: explicit `--workers <N>` pins it; otherwise
  // cores-based auto size is capped by source bytes / CHUNK_BYTES_PER_WORKER
  // so a tiny repo does not spawn a full idle pool. Cache pack membership

View on GitHub (pinned to ac9a4e9abd)