abhigyanpatwari/GitNexus · error · GitNexusRcError

${source} must be a boolean (true/false).

Error message

${source} must be a boolean (true/false).

What it means

Thrown by normalizeValue() in the 'boolean' case (for keys like skipAgentsMd, skipSkills, pdg, indexOnly, stats, dropEmbeddings, allowDuplicateName) when the .gitnexusrc value is not a JSON boolean. The strict type check ensures a config typo (e.g. a string "true") cannot silently no-op a flag that controls analysis behavior.

Source

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

 * Best-effort validation for an auto-detected branch (from git). Never throws —
 * returns `undefined` for anything unusable so the resolver falls back to the
 * next precedence tier.
 */
export function sanitizeDetectedBranch(value: string | null | undefined): string | undefined {
  if (!value) return undefined;
  try {
    return validateBranchName(value, 'detected branch');
  } catch {
    return undefined;
  }
}

const normalizeValue = (kind: ValueKind, value: unknown, key: string): unknown => {
  const source = `${GITNEXUS_RC_FILENAME} "${key}"`;
  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 'string': {
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a string.`);
      }
      const trimmed = value.trim();
      if (!trimmed) {

View on GitHub (pinned to d540b00184)

Solutions

1. Use an unquoted JSON boolean: true or false (no quotes, no 1/0).
2. Run the file through `node -e 'JSON.parse(fs.readFileSync(".gitnexusrc"))'` to confirm it parses.
3. If you need shell-style truthiness, that is not supported — write a real boolean.

Example fix

// before
{ "skipSkills": "true" }

// after
{ "skipSkills": true }

function assertConfigBoolean(value: unknown, key: string): void {
  if (typeof value !== 'boolean') {
    throw new Error(`${key} must be a boolean (true/false), got ${typeof value}`);
  }
}

function isConfigBoolean(value: unknown): value is boolean {
  return typeof value === 'boolean';
}

When it happens

Trigger: Setting a boolean key to a string ("skipSkills": "true"), a number ("stats": 1), or null in .gitnexusrc.

Common situations: Writing config by hand with quoted booleans (common YAML-ism leaked into JSON); a generated config that serialized a boolean as a string; confusing the JSON value type with the CLI flag form.

Related errors

• ${source} must be a string.
• ${source} must be an array of strings.
• ${source} entries must all be strings.
• ${source} must be a string branch name.
• ${GITNEXUS_RC_FILENAME} is not valid JSON: ${(err as Error).

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