abhigyanpatwari/GitNexus · error · GitNexusRcError

${source} must be a string branch name.

Error message

${source} must be a string branch name.

What it means

Thrown by normalizeValue() in the 'branch' case (for defaultBranch / branch keys) when the .gitnexusrc value is not a JSON string. Branch names must be strings before they can be trimmed and validated, so a non-string short-circuits before any refname rule is applied.

Source

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

  }
}

const normalizeValue = (kind: ValueKind, value: unknown, key: string): unknown => {
  const source = `${GITNEXUS_RC_FILENAME} "${key}"`;
  switch (kind) {
    case 'boolean':
      if (typeof value !== 'boolean') {
        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
      }
      return value;
    case 'boolean-negate':
      if (typeof value !== 'boolean') {
        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
      }
      return !value;
    case 'branch':
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a string branch name.`);
      }
      return validateBranchName(value, source);
    case 'string': {
      if (typeof value !== 'string') {
        throw new GitNexusRcError(`${source} must be a string.`);
      }
      const trimmed = value.trim();
      if (!trimmed) {
        throw new GitNexusRcError(`${source} must not be empty.`);
      }
      assertNoHiddenChars(trimmed, source);
      // `name` flows into the generated AGENTS.md/CLAUDE.md as `**${name}**` and
      // inside `gitnexus://repo/${name}/…` code spans, so a Markdown-significant
      // character would break those spans or inject emphasis/links/HTML into
      // agent-instruction content (#1996 tri-review P1). `_` is intentionally
      // allowed (legitimate in repo names; intraword `_` is not emphasis).
      // embeddingDevice (the other `string`-kind option) only ever holds a
      // fixed device token, so this guard never rejects a valid value there.

View on GitHub (pinned to d540b00184)

Solutions

1. Quote the branch name: "defaultBranch": "main".
2. If you want auto-detection, omit the key entirely.
3. Confirm the value is a JSON string, not a number or array.

Example fix

// before
{ "defaultBranch": 123 }

// after
{ "defaultBranch": "main" }

function assertBranchString(value: unknown, key: string): void {
  if (typeof value !== 'string') {
    throw new Error(`${key} must be a string branch name, got ${typeof value}`);
  }
}

function isBranchInput(value: unknown): value is string {
  return typeof value === 'string';
}

When it happens

Trigger: Setting "defaultBranch": 123, "defaultBranch": true, "defaultBranch": null, or "defaultBranch": ["main"] in .gitnexusrc.

Common situations: A generated config that serialized a branch as a non-string; an accidental number where a branch was intended; copy-pasting from a different config format.

Related errors

• ${source}: branch name must not be empty.
• ${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}
• ${source}: branch name must not contain whitespace.
• ${source}: branch name contains characters not allowed in a
• ${source}: branch name must not start with "-".

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