abhigyanpatwari/GitNexus · error · GitNexusRcError

${source} must be a file or directory path.

Error message

${source} must be a file or directory path.

What it means

GitNexusRcError thrown by normalizeValue in analyze-config.ts when a `.gitnexusrc` option declared as type 'path' receives a non-string value (number, boolean, object, etc.). The config loader only accepts strings for path-typed options because paths are later trimmed, checked for hidden characters, and resolved relative to the repo root. The `source` placeholder names the option/origin so you know which key is bad.

Source

Thrown at gitnexus/src/cli/analyze-config.ts:235

  switch (kind) {
    case 'boolean':
      if (typeof value !== 'boolean') {
        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
      }
      return value;
    case 'boolean-negate':
      if (typeof value !== 'boolean') {
        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
      }
      return !value;
    case 'branch':
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a string branch name.`);
      }
      return validateBranchName(value, source);
    case 'path': {
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a file or directory path.`);
      }
      const trimmed = value.trim();
      if (!trimmed) {
        throw new GitNexusRcError(`${source} must not be empty.`);
      }
      assertNoHiddenChars(trimmed, source);
      return trimmed;
    }
    case 'string': {
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a string.`);
      }
      const trimmed = value.trim();
      if (!trimmed) {
        throw new GitNexusRcError(`${source} must not be empty.`);
      }
      assertNoHiddenChars(trimmed, source);
      // `name` flows into the generated AGENTS.md/CLAUDE.md as `**${name}**` and

View on GitHub (pinned to 52924ef12c)

Solutions

1. Open .gitnexusrc (or the config source indicated by `source`) and change the offending option to a quoted string path, e.g. "dist" or "src/output".
2. Check for YAML/JSON type coercion: quote values that look like numbers or booleans if they are meant as paths.
3. If the value comes from a generated config, fix the generator/template to emit strings for path options.
4. Run `npx tsc --noEmit` or the config schema validation if you build the config in TypeScript to catch non-string values before runtime.

Example fix

// before (.gitnexusrc)
output: docs/wiki
maxFileSize: 5242880   // number assigned to a path-typed option

// after (.gitnexusrc)
output: "docs/wiki"
maxFileSize: "build/cache"  // any path option must be a string

function assertPathOption(value: unknown, source: string): void {
  if (typeof value !== 'string') {
    throw new Error(`${source} must be a file or directory path (string), got ${typeof value}`);
  }
}
// run over every path-typed key of the parsed .gitnexusrc before invoking analyze

function isPathOption(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  await loadAnalyzeConfigStrict(repoRoot);
} catch (e) {
  if (e instanceof GitNexusRcError) {
    console.error(`Config error: ${e.message}`);
    process.exitCode = 1; // fix the named key in .gitnexusrc
  } else throw e;
}

When it happens

Trigger: Loading .gitnexusrc / analyze config where a 'path'-kind option (e.g. an output or ignore path key) is set to a number, boolean, null, array or object instead of a string, e.g. `maxFileSize: 100` placed under a path option, or `output: true`.

Common situations: Hand-editing .gitnexusrc and quoting/typing mistakes (unquoted numbers, YAML/JSON5 coercing values), copying an option value from another tool where booleans/numbers are valid, or programmatically building a config object with the wrong field.

Related errors

• ${source} entries must all be strings.
• ${source} entries must not be empty.
• ${source} entry "${trimmed}" must be an identifier or member
• ${source} must list at least one string.
• ${source} must be a finite number.

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-09-01). Data as JSON: /api/errors/c0021ae99ef740d0. Report an issue: GitHub.