abhigyanpatwari/GitNexus · warning · Error

optional icebug build predates the deterministic thread/seed

Error message

optional icebug build predates the deterministic thread/seed controls (icebug-nodejs#6)

What it means

Thrown inside the icebug worker script (generated by buildIcebugWorkerSource) when the loaded icebug native module does not export setNumberOfThreads and setSeed as functions. These are the deterministic thread/seed controls required for reproducible output; they exist at icebug-nodejs HEAD but are missing from the published 12.8.0 tarball. The message references icebug-nodejs#6. This throw happens inside the worker and is posted back as {ok:false, error:...}, then rejected by runIcebugWorker's message handler — which is expected to trip the Graphology fallback.

Source

Thrown at gitnexus/src/core/ingestion/community-processor.ts:620

 * + index.d.ts): `GraphR(n, directed, outIndices, outIndptr)` pins the CSR
 * buffers zero-copy, and `Leiden(graph, iterations, randomize, gamma)` — note
 * `randomize` precedes `gamma` — returns `{membership, count}` from
 * `getPartition()`.
 *
 * The thread/seed controls are required, not optional: community IDs feed
 * generated context, so a build without them would give non-reproducible
 * output. They exist at icebug-nodejs HEAD but are missing from the published
 * 12.8.0 tarball, so today this guard is what trips and sends us back to
 * Graphology.
 */
export const buildIcebugWorkerSource = (moduleSpecifier: string): string => `
const { parentPort, workerData } = require('node:worker_threads');

try {
  const icebug = require(${JSON.stringify(moduleSpecifier)});

  if (typeof icebug.setNumberOfThreads !== 'function' || typeof icebug.setSeed !== 'function') {
    throw new Error(
      'optional icebug build predates the deterministic thread/seed controls (icebug-nodejs#6)',
    );
  }

  icebug.setNumberOfThreads(workerData.threads);
  icebug.setSeed(workerData.seed, false);

  const graph = new icebug.GraphR(
    workerData.nodeCount,
    false,
    workerData.indices,
    workerData.indptr,
  );
  const leiden = new icebug.Leiden(
    graph,
    workerData.iterations,
    workerData.randomize,
    workerData.gamma,

View on GitHub (pinned to d540b00184)

Solutions

This is the expected path for published 12.8.0 — the system falls back to the default Graphology engine. No action is strictly required unless you specifically need icebug.
To actually use icebug, install a build from icebug-nodejs HEAD that includes setNumberOfThreads/setSeed (post icebug-nodejs#6).
If you don't need icebug, switch the engine config back to the default (omit engine: 'icebug') to avoid the worker spin-up that always fails on 12.8.0.
Watch for an icebug npm release newer than 12.8.0 that ships the controls.

Example fix

// before — requesting icebug against published 12.8.0 (always trips this guard)
{ communityDetection: { engine: 'icebug' } }

// after — use the default deterministic Graphology engine
{ communityDetection: { engine: 'graphology' } } // or omit engine entirely

Defensive patterns

Strategy: fallback

Validate before calling

// Probe the installed icebug module for the required controls before
// requesting the engine:
function icebugHasDeterministicControls(icebug: unknown): boolean {
  return typeof (icebug as Record<string, unknown> | null)?.setNumberOfThreads === 'function' &&
    typeof (icebug as Record<string, unknown> | null)?.setSeed === 'function';
}
// if false, fall back to engine:'graphology' instead of requesting 'icebug'.

Type guard

function icebugSupportsDeterminism(mod: unknown): mod is { setNumberOfThreads: (n: number) => void; setSeed: (s: number, r: boolean) => void } {
  return typeof (mod as Record<string, unknown> | null)?.setNumberOfThreads === 'function' &&
    typeof (mod as Record<string, unknown> | null)?.setSeed === 'function';
}

Try / catch

// runIcebugWorker already rejects this and is expected to fall back to Graphology.
// At the caller, catch and degrade:
try { result = await detectCommunitiesIcebug(...); }
catch (err) {
  logger.warn({ msg: (err as Error).message }, 'icebug unavailable — using Graphology');
  result = await detectCommunitiesGraphology(...);
}

Prevention

Prefer the default Graphology engine unless you specifically need icebug.
If you need icebug, install from icebug-nodejs HEAD (post #6) rather than published 12.8.0.
Wrap the icebug call path in a Graphology fallback so a version mismatch degrades gracefully.

When it happens

Trigger: The icebug engine is requested and the installed @ladybugmem/icebug version is 12.8.0 (or another build predating the setNumberOfThread/setSeed additions). The worker loads the module, finds the functions absent, and throws.

Common situations: An operator opted into the optional icebug engine without checking version compatibility; an npm install resolved to the published 12.8.0 tarball; the native dependency was bumped to a version still missing the controls.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/029ddd793ee7bb97. Report an issue: GitHub.