abhigyanpatwari/GitNexus · error · GitNexusRcError

must contain a JSON object.

Error message

${GITNEXUS_RC_FILENAME} must contain a JSON object.

What it means

.gitnexusrc parsed as JSON but the top level is not an object: an array, a bare string/number/boolean, or null all fail the object check at analyze-config.ts:399. The rc file models key/value settings, so only a JSON object at the root is meaningful.

Solutions

1. Make the root an object: {} at minimum, or {"defaultBranch": "develop"}
2. If you intended no config, delete the file entirely — absence is the supported 'no defaults' state
3. Lint the rc file in CI asserting typeof parsed === 'object' && !Array.isArray(parsed)

Example fix

// before (.gitnexusrc)
[]
// after
{}

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

const isJsonObject = (v: unknown): v is Record<string, unknown> =>
  v !== null && typeof v === 'object' && !Array.isArray(v);

catch (err) {
  if (err instanceof GitNexusRcError && err.message.includes('must contain a JSON object')) {
    // replace []/null/scalar with {} and add keys as needed
  }
}

When it happens

Trigger: .gitnexusrc containing [] (common when scaffolding an 'empty' file), "develop", 42, true, or null at the top level.

Common situations: echo [] > .gitnexusrc as a placeholder; converting from a list-style config format; tools that emit a bare scalar for single-value configs.

Related errors

• " " must be a JSON object.
• entries must all be strings.
• is not valid JSON: . Expected a JSON object such as .
• : " " and " " both configure the same option; set only one.
• entries must not be empty.

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-08-20). Data as JSON: /api/errors/7a2c2856117c9347. Report an issue: GitHub.

Appendix: source

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

  // 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 ac9a4e9abd)