abhigyanpatwari/GitNexus · error · GitNexusRcError

is not valid JSON: . Expected a JSON object such as .

Error message

${GITNEXUS_RC_FILENAME} is not valid JSON: ${(err as Error).message}. Expected a JSON object such as {"defaultBranch": "develop", "skipContextFiles": true}.

What it means

The rc file must be strict JSON. After stripping one leading UTF-8 BOM (a deliberate fix so valid files with a BOM still parse), JSON.parse failures throw this error with the parser's message and an example of the expected object shape. Trailing commas, comments, single quotes, or unquoted keys all fail here.

Solutions

Paste the file into a JSON validator — the parser message pinpoints the offending position
Remove comments, trailing commas, and quote all keys/strings with double quotes
Prefer deleting a key over commenting it out; keep the example shape {"defaultBranch": "develop", "skipContextFiles": true}

Example fix

// before (.gitnexusrc)
{
  "defaultBranch": "develop", // mainline
  "skipSkills": true,
}
// after
{
  "defaultBranch": "develop",
  "skipSkills": true
}

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast with a clearer message than the CLI's:
import { readFileSync } from 'node:fs';
const raw = readFileSync('.gitnexusrc', 'utf8').replace(/^\uFEFF/, '');
try {
  JSON.parse(raw);
} catch (e) {
  throw new Error(`.gitnexusrc is not valid JSON: ${(e as Error).message}`);
}

Try / catch

catch (err) {
  if (err instanceof GitNexusRcError && err.message.includes('not valid JSON')) {
    // run the file through `node -e 'JSON.parse(require("fs").readFileSync(".gitnexusrc","utf8"))'` to see the position
  }
}

Prevention

Strict JSON only: no comments, no trailing commas, double quotes everywhere
Validate .gitnexusrc in a pre-commit hook (e.g. prettier --check or jq)
A single leading BOM is tolerated; anything else must be clean JSON

When it happens

Trigger: .gitnexusrc containing JSONC (// comments), a trailing comma after the last key, single-quoted strings, unquoted keys, or stray characters after the closing brace; JSON.parse(raw) throws at analyze-config.ts:392.

Common situations: Hand-editing and commenting values for later; Windows editors appending a BOM plus a comment; merging conflicts that leave a stray comma; pasting YAML fragments.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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

Appendix: source

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

    throw new GitNexusRcError(`Could not read ${GITNEXUS_RC_FILENAME}: ${(err as Error).message}`);
  }
  return raw === null ? undefined : parseAnalyzeConfig(raw);
}

function parseAnalyzeConfig(rawInput: string): Partial<AnalyzeOptions> {
  let raw = rawInput;

  // 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.`);
    }

View on GitHub (pinned to ac9a4e9abd)