abhigyanpatwari/GitNexus · error · Error

${TRUSTED_CACHE_DIRECTORY_ENV} must be outside the analyzer

Error message

${TRUSTED_CACHE_DIRECTORY_ENV} must be outside the analyzer package and build roots

What it means

Thrown by cacheDirectory when the env-var-configured cache directory lies inside the analyzer packageRoot or buildRoot. The cache must be external to both, because writing identity-cache files inside the scanned roots would itself mutate the directory-state guards that the identity receipt depends on — creating a feedback loop that invalidates the cache on every write.

Source

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

): string | null {
  // An explicit location is a trusted operator/test override and therefore
  // remains authoritative, including when the secure default is unavailable.
  if (options.cacheDirectory) {
    const explicit = path.resolve(options.cacheDirectory);
    try {
      // Create it before any build/dependency directory guards are captured.
      // A cache nested immediately under a package root then changes that
      // parent's directory state once, not after we persist the first entry.
      mkdirSync(explicit, { recursive: true, mode: 0o700 });
    } catch {
      /* persistence remains optional and will fail closed */
    }
    return explicit;
  }
  const configured = trustedEnvironmentCacheDirectory();
  if (configured) {
    if (isInside(packageRoot, configured) || isInside(buildRoot, configured)) {
      throw new Error(
        `${TRUSTED_CACHE_DIRECTORY_ENV} must be outside the analyzer package and build roots`,
      );
    }
    return configured;
  }
  return defaultCacheDirectory();
}

function hasTrustedCacheOverride(options: AnalyzerIdentityResolveOptions): boolean {
  return (
    options.cacheDirectory !== undefined || process.env[TRUSTED_CACHE_DIRECTORY_ENV] !== undefined
  );
}

function identityCacheKey(
  packageRoot: string,
  buildRoot: string,
  runtimeVariant: RuntimeVariant,

View on GitHub (pinned to d540b00184)

Solutions

Move the cache outside both roots: `/var/cache/gitnexus-analyzer-identity` or `$HOME/.cache/gitnexus-analyzer-identity`.
Verify: `case "$CACHE" in "$PKG_ROOT"/*|"$BUILD_ROOT"/*) echo overlaps;; esac`.
If you must keep it near the project, put it in a sibling directory (e.g. `../gn-id-cache` resolved to absolute).
If no external writable location exists, unset the env var so the secure default temp location is used (which is already chosen to be external).

Example fix

# before: cache nested inside the package root
#   export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/repo/.cache/gn-id
#   -> "...must be outside the analyzer package and build roots"
#
# after: external writable location
#   export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/var/cache/gitnexus-analyzer-identity
#   mkdir -p /var/cache/gitnexus-analyzer-identity && chmod 700 /var/cache/gitnexus-analyzer-identity

Defensive patterns

Strategy: validation

Validate before calling

const path = require('node:path');
function isInside(parent, candidate) {
  const rel = path.relative(parent, candidate);
  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
}
function validateCacheOutsideRoots(packageRoot, buildRoot) {
  const v = process.env.GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR;
  if (!v) return;
  if (isInside(packageRoot, v) || isInside(buildRoot, v)) {
    throw new Error(`Cache ${v} is inside package/build root; move it outside.`);
  }
}
// validateCacheOutsideRoots(process.cwd(), path.join(process.cwd(),'dist'));

Prevention

Place the cache in a sibling or system directory, never inside the checkout or build output.
Use /var/cache, $HOME/.cache, or a dedicated volume.
If no external location is writable, unset the env var to use the secure default temp location.
Remember: writing inside the scanned roots would invalidate the identity on every cache write.

When it happens

Trigger: trustedEnvironmentCacheDirectory returned a valid external-looking path, but isInside(packageRoot, configured) or isInside(buildRoot, configured) is true. E.g. setting the cache to `<packageRoot>/.cache/gn-id` or `<buildRoot>/../something` that resolves back inside the build tree.

Common situations: Operator tried to keep the cache co-located with the project for convenience (`./.gitnexus-id-cache`); a CI that sets the cache to a subdirectory of the checkout; a monorepo where the cache path was computed relative to the package and landed inside it; a buildRoot that overlaps packageRoot (e.g. `dist/` inside the package).

Related errors

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