abhigyanpatwari/GitNexus · error · Error

local_path is required

Error message

local_path is required

What it means

normalizeConfiguredCloneRoot validates the local_path of an auto-sync clone root. An empty value (after trimming whitespace) has no meaning, so it throws 'local_path is required' immediately at config parse time. The check guarantees downstream path-resolution code always operates on a real path string.

Source

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

    root,
    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, '-');

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Set local_path in the config to the absolute path of the existing clone root directory.
2. If it comes from an environment variable, export that variable before running.
3. Re-run parseAutoSyncConfig to confirm the config loads.

Example fix

// before (config)
local_path: ""
// after (config)
local_path: "/home/dev/work/gitnexus-clones"

const localPath = process.env.CLONE_ROOT ?? '';
if (!localPath.trim()) throw new Error('local_path must be set to a non-empty absolute path before loading auto-sync config');

function hasLocalPath(cfg: unknown): cfg is { local_path: string } {
  return typeof cfg === 'object' && cfg !== null && 'local_path' in cfg && typeof (cfg as any).local_path === 'string' && (cfg as any).local_path.trim() !== '';
}

try {
  parseAutoSyncConfig(raw);
} catch (err) {
  if (err.message === 'local_path is required') {
    console.error('Set local_path in the auto-sync config to an existing absolute directory.');
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: parseAutoSyncConfig is called with local_path set to "", " ", or null/undefined coerced to an empty string.

Common situations: Missing local_path key in the auto-sync config file, an env var placeholder that expanded to empty (e.g. ${CLONE_ROOT} unset), or YAML with `local_path:` left blank.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• local_path must be an absolute path
• must not contain backticks
• must not end with "/" or "."
• must not contain consecutive slashes
• must not contain "@{"

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