abhigyanpatwari/GitNexus · error

${TRUSTED_CACHE_DIRECTORY_ENV} must name an absolute protect

Error message

${TRUSTED_CACHE_DIRECTORY_ENV} must name an absolute protected directory

What it means

Thrown by trustedEnvironmentCacheDirectory when GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR is set but the value is empty, contains a NUL byte, or is not an absolute path. This is the first syntax/trust gate on the operator-provided cache location; the env var is an explicit trust assertion, so its spelling must be a valid absolute filesystem path.

Source

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

  try {
    tempRoot = realpathSync.native(os.tmpdir());
  } catch {
    return null;
  }
  return ensurePrivateChild(tempRoot, `gitnexus-analyzer-identity-${uid}`);
}

const TRUSTED_CACHE_DIRECTORY_ENV = 'GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR';

function pathsEqual(left: string, right: string): boolean {
  return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
}

function trustedEnvironmentCacheDirectory(): string | null {
  const configured = process.env[TRUSTED_CACHE_DIRECTORY_ENV];
  if (configured === undefined) return null;
  if (configured.length === 0 || configured.includes('\0') || !path.isAbsolute(configured)) {
    throw new Error(`${TRUSTED_CACHE_DIRECTORY_ENV} must name an absolute protected directory`);
  }
  const normalized = path.normalize(configured);
  let resolved: string;
  try {
    const link = lstatSync(normalized);
    if (!link.isDirectory() || link.isSymbolicLink()) {
      throw new Error('not a real directory');
    }
    resolved = realpathSync.native(normalized);
  } catch {
    throw new Error(
      `${TRUSTED_CACHE_DIRECTORY_ENV} must name a pre-existing protected non-symlink directory`,
    );
  }
  // Reject junctions/symlinked ancestors as well as a symlink final component.
  // The environment variable is an explicit trust assertion, but its spelling
  // must still bind exactly to the directory the cache will use.
  if (!pathsEqual(path.resolve(normalized), resolved)) {

View on GitHub (pinned to d540b00184)

Solutions

1. Set an absolute path with no tilde and no NUL: `export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/var/cache/gitnexus-analyzer-identity`.
2. Verify the value: `printf '%s' "$GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR" | od -c` to spot embedded NULs or whitespace.
3. If unset is desired, `unset GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR` so the secure default temp location is used.
4. On Windows use a drive-absolute path like `C:\ProgramData\gitnexus-analyzer-identity`.

Example fix

# before: relative path with unexpanded tilde
#   export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR='~/.cache/gn-id'
#   -> "GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR must name an absolute protected directory"
#
# after: absolute, expanded
#   export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR="$HOME/.cache/gn-id"

function validateTrustedCacheEnv() {
  const v = process.env.GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR;
  if (v === undefined) return null; // unset is fine
  if (v.length === 0) throw new Error('GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR is empty');
  if (v.includes('\0')) throw new Error('GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR contains a NUL byte');
  const path = require('node:path');
  if (!path.isAbsolute(v)) throw new Error(`GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR is not absolute: ${v}`);
  return v;
}
// validateTrustedCacheEnv();

When it happens

Trigger: resolveAnalyzerRunnerIdentity -> cacheDirectory -> trustedEnvironmentCacheDirectory reads process.env.GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR. If the value fails any of `length===0`, `includes('\0')`, or `!path.isAbsolute(value)`, it throws before any stat call. Common when the env var was exported empty (`export GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=`) or set to a relative path or a tilde path.

Common situations: A shell that did not substitute `$VAR` (so the literal `$VAR` or empty string was exported); using `~/.cache/...` (tilde is not expanded inside env values); a CI secret that resolved to empty; a Windows path without a drive letter; a copy-paste that included a leading space or quote.

Related errors

• ${TRUSTED_CACHE_DIRECTORY_ENV} must name a pre-existing prot
• ${TRUSTED_CACHE_DIRECTORY_ENV} must not traverse symbolic li
• ${TRUSTED_CACHE_DIRECTORY_ENV} must be outside the analyzer
• GitNexus package version is unavailable in ${packageRoot}
• Analyzer dependency graph exceeded ${limits.runtimeEdges} ed

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