abhigyanpatwari/GitNexus · critical · Error

Cannot resolve GitNexus package root from analyzer module: $

Error message

Cannot resolve GitNexus package root from analyzer module: ${analyzerModulePath}

What it means

resolveBuildRoot() walks up from the analyzer module's real path looking for a directory literally named 'src' or 'dist' whose parent contains a regular package.json file; that parent becomes the GitNexus package root. If the walk reaches the filesystem root without a match, identity resolution cannot proceed because build digest, dependency runtime, and the version string are all anchored at that package root, so it throws with the module path that failed.

Source

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

        // and (via collectDependencyInputs) dependencyRuntime.manifestPath /
        // lockfilePath — inherits a case-stable root and analyze-stamp equals
        // status-recompute regardless of launch-path casing (#2668).
        // Migration: a Windows index stamped before this fix carries the old,
        // un-normalized casing, so the first post-upgrade `status` sees one
        // spurious "stale" flip — self-healing on the next `analyze`, which
        // re-stamps the normalized (idempotent) form.
        return {
          packageRoot: normalizeAnalyzerRootPath(packageRoot, process.platform),
          buildRoot: normalizeAnalyzerRootPath(cursor, process.platform),
          kind: base === 'src' ? 'source' : 'distribution',
        };
      }
    }
    const parent = path.dirname(cursor);
    if (parent === cursor) break;
    cursor = parent;
  }
  throw new Error(
    `Cannot resolve GitNexus package root from analyzer module: ${analyzerModulePath}`,
  );
}

function compareBytes(a: string, b: string): number {
  return Buffer.compare(Buffer.from(a), Buffer.from(b));
}

function collectBuildEntries(
  buildRoot: string,
  options: AnalyzerIdentityResolveOptions,
  limits: AnalyzerIdentityTraversalLimits,
): BuildEntry[] {
  const entries: BuildEntry[] = [];
  const pending: Array<{ absoluteDir: string; depth: number }> = [
    { absoluteDir: buildRoot, depth: 0 },
  ];
  let scannedEntries = 0;

View on GitHub (pinned to 52924ef12c)

Solutions

Run gitnexus from a standard install ('npx gitnexus', global install, or repo checkout) where <packageRoot>/dist (or /src) sits next to <packageRoot>/package.json.
Reinstall the package to repair a corrupted install: rm -rf node_modules/gitnexus && npm install.
If you forked/repackaged gitnexus, keep the output directory named 'dist' (or run from 'src') with package.json one level above it.
Avoid bundling the analyzer module graph into artifacts that erase the directory layout (single-file executables, PnP zips).

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, statSync } from 'node:fs';
import path from 'node:path';

function hasResolvablePackageRoot(analyzerModulePath: string): boolean {
  let cursor = path.dirname(path.resolve(analyzerModulePath));
  while (true) {
    const base = path.basename(cursor);
    if (base === 'src' || base === 'dist') {
      const packageJson = path.join(path.dirname(cursor), 'package.json');
      try {
        return statSync(packageJson).isFile();
      } catch {
        return false;
      }
    }
    const parent = path.dirname(cursor);
    if (parent === cursor) return false;
    cursor = parent;
  }
}

Type guard

function isPackageRootResolutionError(error: unknown): boolean {
  return error instanceof Error && /^Cannot resolve GitNexus package root from analyzer module:/.test(error.message);
}

Try / catch

try {
  identity = resolveAnalyzerRunnerIdentity(import.meta.url);
} catch (error) {
  if (isPackageRootResolutionError(error)) {
    failFast('gitnexus must run from a standard install where dist/ (or src/) sits next to package.json; reinstall or unbundle.');
  }
  throw error;
}

Prevention

Run gitnexus from a real npm install or repo checkout, not a bundled single-file artifact.
If you fork gitnexus, keep the build output directory named dist (or run from src) with package.json one level up.
Smoke-test deployments with 'gitnexus status' before relying on analyze.

When it happens

Trigger: resolveAnalyzerRunnerIdentity(analyzerModuleUrl) where the module does not live under .../src or .../dist adjacent to a package.json — e.g. the code was bundled into a single file (esbuild/rollup/pkg/bun compile), the dist directory was renamed (lib/, build/out/), package.json was deleted from the install, or the module path resolves into a virtual filesystem (snapshots, PnP zip archives) where the layout probe fails.

Common situations: Packaging gitnexus into a custom bundler or single-file executable; renaming output directories in a fork; a corrupted half-deleted npm install missing package.json; running from a yarn PnP or patched-module layout that hides the real directory shape.

Related errors

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