abhigyanpatwari/GitNexus · error · GitNexusRcError

${GITNEXUS_RC_FILENAME} "${NESTED_KEY}" must be a JSON objec

Error message

${GITNEXUS_RC_FILENAME} "${NESTED_KEY}" must be a JSON object.

What it means

The nested `analyze` key is present in `.gitnexusrc` but its value is not a JSON object — it is an array, string, number, boolean, or null. The nested block must itself be an object holding the same allowed keys.

Source

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

  } catch (err) {
    throw new GitNexusRcError(
      `${GITNEXUS_RC_FILENAME} is not valid JSON: ${(err as Error).message}. ` +
        `Expected a JSON object such as {"defaultBranch": "develop", "skipContextFiles": true}.`,
    );
  }

  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME} must contain a JSON object.`);
  }

  const obj = parsed as Record<string, unknown>;
  const flat = normalizeLevel(obj, { allowNestedKey: true });

  let nested: Partial<AnalyzeOptions> = {};
  if (Object.prototype.hasOwnProperty.call(obj, NESTED_KEY)) {
    const nestedRaw = obj[NESTED_KEY];
    if (nestedRaw === null || typeof nestedRaw !== 'object' || Array.isArray(nestedRaw)) {
      throw new GitNexusRcError(`${GITNEXUS_RC_FILENAME} "${NESTED_KEY}" must be a JSON object.`);
    }
    nested = normalizeLevel(nestedRaw as Record<string, unknown>, { allowNestedKey: false });
  }

  // Nested `analyze` block overrides flat top-level keys for the same option.
  return { ...flat, ...nested };
}

/**
 * Merge CLI options over `.gitnexusrc` defaults. CLI wins whenever it provides a
 * value — including an explicit `false` (so an explicit CLI off-switch beats a
 * config `true`). Config fills only the genuinely-unset (`undefined`) options.
 *
 * `stats` is special: Commander always materializes it (`true` by default,
 * `false` only when `--no-stats` is passed), so plain `??` can't tell "default
 * on" from "explicitly on". The rule is: a passed `--no-stats` (`stats: false`)
 * always wins; otherwise the config value applies. There is intentionally no
 * `--stats` counter-flag, so config can only turn stats off, not force it back

View on GitHub (pinned to d540b00184)

Solutions

1. Make the `analyze` value a JSON object, e.g. { "analyze": { "defaultBranch": "develop" } }.
2. Omit the `analyze` key entirely if you have no nested overrides.

Example fix

// before
{"analyze": []}
// after
{"analyze": {"defaultBranch": "develop"}}

if (Object.prototype.hasOwnProperty.call(parsed, 'analyze')) {
  const nested = parsed.analyze;
  if (nested === null || typeof nested !== 'object' || Array.isArray(nested)) {
    throw new Error('.gitnexusrc "analyze" must be a JSON object');
  }
}

const isAnalyzeBlock = (v) =>
  v !== null && typeof v === 'object' && !Array.isArray(v);

When it happens

Trigger: Setting { "analyze": [] }, { "analyze": "develop" }, or { "analyze": null }.

Common situations: Confusing the nested `analyze` block with a list; templating that emits an array for the nested section; setting null intending to disable the nested block (omit the key instead).

Related errors

• ${GITNEXUS_RC_FILENAME} is not valid JSON: ${(err as Error).
• ${GITNEXUS_RC_FILENAME} must contain a JSON object.
• ${source} must be a boolean (true/false).
• ${source} must be a string.
• ${source} must be an array of strings.

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