analyze finalization not visible after timeout; completing j

Error message

analyze finalization not visible after timeout; completing job anyway

What it means

After dispatching an analyze job to a worker, the launcher polls the repo's registered storage path (re-resolved each round, because the worker registers the repo during the finalization being waited on) until finalization settles. If FINALIZE_SETTLE_TIMEOUT_MS elapses without the settled state becoming observable, this warning fires and the job is completed anyway rather than blocking forever: the gate trades a possibly stale completion signal for liveness.

Source

Thrown at gitnexus/src/server/analyze-launch.ts:117

      return (
        lbugStat.mtimeMs >= jobStartMs &&
        metaStat.mtimeMs >= jobStartMs &&
        ['lbug.wal', 'lbug.shadow', 'lbug.wal.checkpoint'].every(
          (f) => !existsSync(path.join(storagePath, f)),
        )
      );
    } catch {
      return false; // not written yet
    }
  };
  const deadline = Date.now() + FINALIZE_SETTLE_TIMEOUT_MS;
  for (;;) {
    // Re-resolved each round: the worker registers the repo as part of the
    // finalization this gate is waiting out.
    const storagePath = await registeredStoragePath(targetPath);
    if (storagePath && settled(storagePath)) return;
    if (Date.now() > deadline) {
      logger.warn(
        { targetPath },
        'analyze finalization not visible after timeout; completing job anyway',
      );
      return;
    }
    await new Promise((resolve) => setTimeout(resolve, FINALIZE_SETTLE_POLL_MS));
  }
};

export function createLaunchAnalysisWorker(deps: LaunchDeps) {
  const { jobManager, backend, acquireRepoLock, releaseRepoLock, closeDbHandle } = deps;

  return function launchAnalysisWorker(
    job: { id: string },
    targetPath: string,
    opts: LaunchOptions,
  ): void {
    // For waitForSettledIndex: files (re)written by this job have mtimes at or

View on GitHub (pinned to 0d1aed942f)

Solutions

After the job reports complete, check index freshness (gitnexus status); if stale, simply re-run analyze
Inspect worker logs for a crash or OOM during finalization and fix that root cause
Reduce concurrent analyze jobs so finalization I/O is not starved
Move the index storage path off a slow network mount onto local disk
If a consistently huge repo keeps tripping it, report it so FINALIZE_SETTLE_TIMEOUT_MS can be raised

Defensive patterns

Strategy: retry

Validate before calling

// 'Job completed' is provisional when this warning fired: verify the
// finalization actually landed before trusting the index.
const storagePath = await registeredStoragePath(targetPath);
const meta = storagePath ? await loadMeta(storagePath) : undefined;
if (!meta || !settled(storagePath)) {
  await relaunchAnalyze(targetPath); // analyze is idempotent — just run it again
}

Prevention

Treat analyze-job completion as provisional; always verify index freshness afterwards
Keep index storage on local fast disk, not a network mount
Avoid stacking many concurrent analyses on one volume

When it happens

Trigger: A server-launched analyze job whose finalization artifacts (repo registration plus index writes) do not become visible within the settle timeout: saturated or very slow disk, the worker crashing or being OOM-killed mid-finalize, many concurrent analyze jobs contending for I/O, or a network filesystem delaying visibility.

Common situations: Very large repositories whose finalization flush exceeds the timeout; containers with slow volumes; NFS/high-latency home dirs for storage; overlapping scheduled analyses starving each other's I/O; worker killed during finalize.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-08-20). Data as JSON: /api/errors/5422340be62e5155. Report an issue: GitHub.