What causes "local_path must be an absolute path" in abhigyanpatwari/GitNexus?

Replace the relative path with an absolute one (e.g. /home/user/clones).

abhigyanpatwari/GitNexus · error · Error

local_path must be an absolute path

Error message

local_path must be an absolute path

What it means

normalizeConfiguredCloneRoot requires local_path to be an absolute path. Relative paths are ambiguous because they depend on the working directory of the auto-sync process, so they are rejected with 'local_path must be an absolute path' before any filesystem access.

Source

Thrown at gitnexus/src/core/auto-sync/path-security.ts:108

    realRoot,
    'Configured clone root realpath escaped its normalized path',
  );
  assertNotDangerousRoot(realRoot);
  assertNotGitNexusInternalRoot(realRoot);
  const quarantineRoot = path.join(getAutoSyncWatchDir(), 'quarantine');
  await pruneQuarantineEntries(quarantineRoot);

  return {
    root: realRoot,
    quarantineRoot,
    quarantineRetentionDays: QUARANTINE_RETENTION_DAYS,
  };
}

export function normalizeConfiguredCloneRoot(localPath: string): string {
  const value = localPath.trim();
  if (!value) throw new Error('local_path is required');
  if (!path.isAbsolute(value)) throw new Error('local_path must be an absolute path');
  if (value.split(path.sep).includes('..')) {
    throw new Error('local_path must be normalized and must not contain traversal segments');
  }
  const resolved = path.resolve(value);
  if (resolved !== path.normalize(value)) {
    throw new Error('local_path must be normalized and must not contain traversal segments');
  }
  return resolved;
}

export async function quarantineAutoSyncPartial(
  targetDir: string,
  quarantineRoot: string,
): Promise<string> {
  await fs.mkdir(quarantineRoot, { recursive: true, mode: 0o700 });
  const base = path.basename(targetDir);
  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
  const destination = path.join(

View on GitHub (pinned to 0d1aed942f)

Solutions

Replace the relative path with an absolute one (e.g. /home/user/clones).
If the value comes from an env var, resolve it to absolute form before writing config (e.g. $(pwd)/clones).
Re-run parseAutoSyncConfig to confirm validation passes.

Example fix

// before (config)
local_path: "./clones"
// after (config)
local_path: "/home/dev/projects/clones"

Defensive patterns

Strategy: validation

Validate before calling

if (localPath.trim() && !path.isAbsolute(localPath.trim())) throw new Error('local_path must be an absolute path');

Try / catch

try {
  parseAutoSyncConfig(raw);
} catch (err) {
  if (err.message === 'local_path must be an absolute path') {
    console.error('Provide local_path as an absolute path, e.g. ' + path.resolve(localPath));
  } else throw err;
}

Prevention

Anchor relative values at startup: path.resolve(process.cwd(), relative) before writing config.
Store absolute paths in config files; keep them environment-specific via env expansion.
Add a config check that asserts path.isAbsolute(local_path).

When it happens

Trigger: parseAutoSyncConfig receives a local_path like "clones" or "./repos/x" (no leading "/" on POSIX, no drive/root on Windows).

Common situations: Configs written for portability with relative paths, values copied from a terminal where the user was in the target directory, or Docker-relative assumptions.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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