abhigyanpatwari/GitNexus · error · GitNexusRcError

${GITNEXUS_RC_FILENAME} must contain a JSON object.

Error message

${GITNEXUS_RC_FILENAME} must contain a JSON object.

What it means

`.gitnexusrc` parsed as valid JSON, but the top-level value is not a JSON object — it is an array, a bare string/number/boolean, or null. GitNexus requires a top-level object (flat keys and/or a nested `analyze` block).

Source

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

  // Strip a leading UTF-8 BOM: Node's 'utf-8' decode keeps it, and JSON.parse
  // then fails with a confusing "Unexpected token" on an otherwise-valid file
  // (#1996 tri-review). Only one leading BOM is stripped; in-string control
  // rejection still applies to the parsed values.
  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } 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 };
}

View on GitHub (pinned to d540b00184)

Solutions

1. Wrap the content in a JSON object with the documented key names.
2. If the file was scratch, replace it with a valid object or delete it.

Example fix

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

const parsed = JSON.parse(raw);
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
  throw new Error('.gitnexusrc must contain a JSON object');
}

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

When it happens

Trigger: File contents [], ["defaultBranch", "develop"], "develop", 42, or null.

Common situations: Treating `.gitnexusrc` as a list of strings; leftover scratch content written into the file; a generator that emits an array instead of an object.

Related errors

• ${GITNEXUS_RC_FILENAME} is not valid JSON: ${(err as Error).
• ${GITNEXUS_RC_FILENAME} "${NESTED_KEY}" must be a JSON objec
• ${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/7a2c2856117c9347. Report an issue: GitHub.