abhigyanpatwari/GitNexus · error · GitNexusRcError

Unknown key " " in .

Error message

Unknown key "${key}" in ${GITNEXUS_RC_FILENAME}. ${ALLOWED_KEYS_HINT}

What it means

.gitnexusrc only accepts a fixed key set (the message embeds ALLOWED_KEYS_HINT listing them, plus the nested "analyze" object). Any key not in KEY_SPECS — including inherited prototype names like __proto__, which Object.hasOwn explicitly filters — throws this GitNexusRcError during loadAnalyzeConfig.

Solutions

1. Read the Allowed-keys list printed in the error and rename/remove the unknown key
2. Check for spelling: e.g. defaultBranch/branch, skipAgentsMd/skipContextFiles/skipAiContext, skipSkills, pdg, indexOnly, stats/noStats, embeddings, dropEmbeddings, name, allowDuplicateName, maxFileSize, workerTimeout, walCheckpointThreshold, workers, embeddingThreads, embeddingBatchSize, embeddingSubBatchSize, embeddingDevice, fetchWrappers, embeddingBaseUrl, embeddingModel
3. Keys may also live inside a nested "analyze" object — group them there if you prefer

Example fix

// before (.gitnexusrc)
{"default_branch": "develop", "verbose": true}
// after
{"defaultBranch": "develop"}

import { readFileSync } from 'node:fs';
const ALLOWED = new Set(['defaultBranch','branch','skipAgentsMd','skipContextFiles','skipAiContext','skipSkills','pdg','indexOnly','stats','noStats','embeddings','dropEmbeddings','name','allowDuplicateName','maxFileSize','workerTimeout','walCheckpointThreshold','workers','embeddingThreads','embeddingBatchSize','embeddingSubBatchSize','embeddingDevice','fetchWrappers','embeddingBaseUrl','embeddingModel','analyze']);
const rc = JSON.parse(readFileSync('.gitnexusrc', 'utf8'));
const unknown = Object.keys(rc).filter((k) => !ALLOWED.has(k));
if (unknown.length) throw new Error(`Unknown .gitnexusrc keys: ${unknown.join(', ')}`);

const isKnownRcKey = (k: string): boolean => ALLOWED.has(k);

catch (err) {
  if (err instanceof GitNexusRcError && err.message.includes('Unknown key')) {
    // the message already lists every allowed key — diff your file against it
  }
}

When it happens

Trigger: A typo ("skipAgentMd", "default_branch"), an invented key ("verbose": true), or a key placed one level too deep (e.g. inside "analyze" a key that only exists flat, or vice versa where not allowed); also duplicate-concept keys are fine individually but unknown ones never are.

Common situations: Upgrading GitNexus and using keys documented for a different version; converting settings from another tool's config format; editors auto-completing wrong key names; CI templates drift.

Related errors

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

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

Appendix: source

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

 * Normalize one level (flat top-level or the nested `analyze` block) into a
 * partial `AnalyzeOptions`. Rejects unknown keys and two aliases that configure
 * the same option at the same level.
 */
const normalizeLevel = (
  obj: Record<string, unknown>,
  { allowNestedKey }: { allowNestedKey: boolean },
): Partial<AnalyzeOptions> => {
  const out: Partial<AnalyzeOptions> = {};
  const setBy = new Map<keyof AnalyzeOptions, string>();

  for (const [key, value] of Object.entries(obj)) {
    if (allowNestedKey && key === NESTED_KEY) continue; // handled separately
    // `Object.hasOwn`, not a truthiness check: a plain-object lookup like
    // `KEY_SPECS["__proto__"]` returns an inherited member (Object.prototype,
    // truthy) and would slip past `if (!spec)`, hitting the wrong error branch
    // instead of the documented "Unknown key" message (#1996 tri-review P3).
    if (!Object.hasOwn(KEY_SPECS, key)) {
      throw new GitNexusRcError(
        `Unknown key "${key}" in ${GITNEXUS_RC_FILENAME}. ${ALLOWED_KEYS_HINT}`,
      );
    }
    const spec = KEY_SPECS[key];
    const prev = setBy.get(spec.target);
    if (prev && prev !== key) {
      throw new GitNexusRcError(
        `${GITNEXUS_RC_FILENAME}: "${prev}" and "${key}" both configure the same option; set only one.`,
      );
    }
    setBy.set(spec.target, key);
    (out as Record<string, unknown>)[spec.target] = normalizeValue(spec.kind, value, key);
  }

  return out;
};

/**

View on GitHub (pinned to ac9a4e9abd)