Analyzer runtime payload directory is unavailable

Error message

Analyzer runtime payload directory is unavailable: ${absoluteDir}

What it means

Before scanning a runtime payload directory, the code records a directory-inventory guard (double-read stat + entries digest); if that snapshot fails — directory deleted, replaced by a file, made unreadable, or unstable across the guard's two reads — recordDirectoryGuard returns false and this error throws with the directory path. Guards exist because the identity receipt must remain verifiable after the fact: a directory whose inventory could not even be captured cannot be covered.

Solutions

Re-run once installs/upgrades/cleanups of the gitnexus tree have finished — the condition is transient.
Serialize package-manager operations and analyze runs in CI scripts.
Ensure the process has stable read access (permissions, mounted volumes) to the analyzer's node_modules for the whole run.

Defensive patterns

Strategy: retry

Type guard

function isPayloadDirectoryUnavailableError(error: unknown): boolean {
  return error instanceof Error && /^Analyzer runtime payload directory is unavailable:/.test(error.message);
}

Try / catch

try {
  identity = resolveAnalyzerRunnerIdentity(import.meta.url);
} catch (error) {
  if (!isPayloadDirectoryUnavailableError(error)) throw error;
  await sleep(500); // wait out the concurrent uninstall/cache eviction
  identity = resolveAnalyzerRunnerIdentity(import.meta.url);
}

Prevention

Do not uninstall/upgrade the analyzer's node_modules while analyze or status is running.
Disable CI cache eviction/prune steps that touch node_modules during the analysis job.
Ensure stable read permissions on the analyzer install for the whole run.

When it happens

Trigger: A dependency package directory disappearing or being swapped mid-scan — concurrent 'npm uninstall'/'npm update' removing the package, a package manager garbage-collecting a store, or permissions changing under the process — while collectArtifacts walks runtime package trees during analyze/status.

Common situations: Analyzer runs racing an install/upgrade in another terminal; CI cache eviction pruning node_modules during the job; Docker layers or FUSE mounts lazily evicting directories; two gitnexus processes scanning while one cleans.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/analyzer-identity.ts:1322

  return lower !== 'package.json';
}

function collectArtifacts(
  root: string,
  canonicalPrefix: string,
  directoryGuards: Map<string, DependencyDirectoryGuard>,
  options: AnalyzerIdentityResolveOptions,
  budget: RuntimeArtifactScanBudget,
  limits: AnalyzerIdentityTraversalLimits,
): RuntimeArtifact[] {
  const artifacts: RuntimeArtifact[] = [];
  const pending: Array<{ absoluteDir: string; depth: number }> = [{ absoluteDir: root, depth: 0 }];
  while (pending.length > 0) {
    const next = pending.pop();
    if (!next) break;
    const { absoluteDir, depth } = next;
    if (!recordDirectoryGuard(directoryGuards, absoluteDir)) {
      throw new Error(`Analyzer runtime payload directory is unavailable: ${absoluteDir}`);
    }
    const entries = readDirectory(absoluteDir, options);
    budget.entries += entries.length;
    if (budget.entries > limits.runtimeEntries) {
      throw new Error(
        `Analyzer runtime payload scan exceeded ${limits.runtimeEntries} entries: ${root}`,
      );
    }
    for (const entry of entries) {
      const absolutePath = path.join(absoluteDir, entry.name);
      const relativePath = path.relative(root, absolutePath).split(path.sep).join('/');
      const stat = lstatSync(absolutePath);
      // Nested dependencies are collected from their manifests as separate
      // packages. Only prune those separately traversed trees and VCS
      // metadata; generic cache/model directories can contain loadable code,
      // native addons, Wasm modules, or data consumed by the runtime.
      //
      // Pruning is decided by NAME alone. These four names never carry analyzer

View on GitHub (pinned to 52924ef12c)