{"record":{"id":"88589f6827e249e8","repo":"abhigyanpatwari/GitNexus","slug":"source-must-be-a-string-branch-name","errorCode":null,"errorMessage":"${source} must be a string branch name.","messagePattern":"(.+?) must be a string branch name\\.","errorType":"validation","errorClass":"GitNexusRcError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/cli/analyze-config.ts","lineNumber":225,"sourceCode":"  }\n}\n\nconst normalizeValue = (kind: ValueKind, value: unknown, key: string): unknown => {\n  const source = `${GITNEXUS_RC_FILENAME} \"${key}\"`;\n  switch (kind) {\n    case 'boolean':\n      if (typeof value !== 'boolean') {\n        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);\n      }\n      return value;\n    case 'boolean-negate':\n      if (typeof value !== 'boolean') {\n        throw new GitNexusRcError(`${source} must be a boolean (true/false).`);\n      }\n      return !value;\n    case 'branch':\n      if (typeof value !== 'string') {\n        throw new GitNexusRcError(`${source} must be a string branch name.`);\n      }\n      return validateBranchName(value, source);\n    case 'string': {\n      if (typeof value !== 'string') {\n        throw new GitNexusRcError(`${source} must be a string.`);\n      }\n      const trimmed = value.trim();\n      if (!trimmed) {\n        throw new GitNexusRcError(`${source} must not be empty.`);\n      }\n      assertNoHiddenChars(trimmed, source);\n      // `name` flows into the generated AGENTS.md/CLAUDE.md as `**${name}**` and\n      // inside `gitnexus://repo/${name}/…` code spans, so a Markdown-significant\n      // character would break those spans or inject emphasis/links/HTML into\n      // agent-instruction content (#1996 tri-review P1). `_` is intentionally\n      // allowed (legitimate in repo names; intraword `_` is not emphasis).\n      // embeddingDevice (the other `string`-kind option) only ever holds a\n      // fixed device token, so this guard never rejects a valid value there.","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/cli/analyze-config.ts#L207-L243","documentation":"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.","triggerScenarios":"Setting \"defaultBranch\": 123, \"defaultBranch\": true, \"defaultBranch\": null, or \"defaultBranch\": [\"main\"] in .gitnexusrc.","commonSituations":"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.","solutions":["Quote the branch name: \"defaultBranch\": \"main\".","If you want auto-detection, omit the key entirely.","Confirm the value is a JSON string, not a number or array."],"exampleFix":"// before\n{ \"defaultBranch\": 123 }\n\n// after\n{ \"defaultBranch\": \"main\" }","handlingStrategy":"type-guard","validationCode":"function assertBranchString(value: unknown, key: string): void {\n  if (typeof value !== 'string') {\n    throw new Error(`${key} must be a string branch name, got ${typeof value}`);\n  }\n}","typeGuard":"function isBranchInput(value: unknown): value is string {\n  return typeof value === 'string';\n}","tryCatchPattern":null,"preventionTips":["Quote branch values in JSON: \"defaultBranch\": \"main\".","Omit the key when you want auto-detection rather than passing null/0.","Do not pass arrays or objects where a branch name is expected."],"tags":["validation","config","branch","typescript"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}