{"record":{"id":"596e899181614c2d","repo":"abhigyanpatwari/GitNexus","slug":"unsupported-group-yaml-version-raw-version-ex","errorCode":null,"errorMessage":"Unsupported group.yaml version: ${raw.version}. Expected 1.","messagePattern":"Unsupported group\\.yaml version: (.+?)\\. Expected 1\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/group/config-parser.ts","lineNumber":56,"sourceCode":"  includes: false,\n  workspace_deps: false,\n};\n\nconst DEFAULT_MATCHING = {\n  exclude_links_paths: [] as string[],\n  exclude_links_param_only_paths: false,\n};\n\nexport function parseGroupConfig(yamlContent: string): GroupConfig {\n  const raw = yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;\n\n  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {\n    throw new Error('Invalid YAML: expected an object');\n  }\n\n  if (raw.version === undefined) throw new Error('version is required in group.yaml');\n  if (raw.version !== 1) {\n    throw new Error(`Unsupported group.yaml version: ${raw.version}. Expected 1.`);\n  }\n  if (!raw.name || typeof raw.name !== 'string') throw new Error('name is required in group.yaml');\n  if (!raw.repos || typeof raw.repos !== 'object' || Array.isArray(raw.repos)) {\n    throw new Error('repos is required in group.yaml (must be a mapping)');\n  }\n\n  const reposRaw = raw.repos as Record<string, unknown>;\n  const repos: Record<string, string> = {};\n  for (const [memberPath, registryName] of Object.entries(reposRaw)) {\n    if (typeof registryName !== 'string' || registryName.trim() === '') {\n      throw new Error(\n        `repos[\"${memberPath}\"] must be a non-empty registry name string, not ${typeof registryName}`,\n      );\n    }\n    repos[memberPath] = registryName.trim();\n  }\n  const repoPaths = new Set(Object.keys(repos));\n","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/52924ef12c2290ceee4612526a828ec4cdf2047f/gitnexus/src/core/group/config-parser.ts#L38-L74","documentation":"Thrown by parseGroupConfig() when group.yaml has a `version` key whose value is not exactly the number 1. The check is a strict !== 1, so any other number (2, 0), a string (\"1\", \"v1\"), or a decorated value (1.0 is fine, but 1-beta is not) is rejected. Only version 1 of the manifest format exists, so anything else means an unknown future format or a typo.","triggerScenarios":"Loading a group.yaml with version: 2 (a manifest authored for a newer gitnexus), version: \"1\" quoted as a string, version: v1, or version: 1.0-beta style decorations — all fail the strict equality against the number 1.","commonSituations":"A teammate edits the file on a newer gitnexus release that supports version 2 and you sync with an older CLI; quoting the value out of habit; writing v1 as in some other tools' manifests.","solutions":["Set the value to the unquoted number: `version: 1`.","If the file legitimately uses a newer version, upgrade gitnexus to a release that supports that manifest version instead of downgrading the file.","Remove quotes/prefixes: \"1\", v1, and 1-beta all fail; plain 1 passes."],"exampleFix":"# before (group.yaml)\nversion: \"1\"\nname: my-group\n# -> Error: Unsupported group.yaml version: 1 (as string). Expected 1.\n\n# after\nversion: 1\nname: my-group","handlingStrategy":"validation","validationCode":"import yaml from 'js-yaml';\n\nexport function checkGroupVersion(content: string): void {\n  const doc = yaml.load(content, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;\n  if (doc.version !== 1) {\n    throw new Error(\n      `group.yaml version must be the number 1 (unquoted); got ${JSON.stringify(doc.version)}`,\n    );\n  }\n}","typeGuard":"export const isSupportedGroupVersion = (v: unknown): v is 1 => v === 1;","tryCatchPattern":"try {\n  config = await loadGroupConfig(groupDir);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unsupported group.yaml version')) {\n    const found = /version: (.+?)\\./.exec(err.message)?.[1];\n    throw new Error(\n      found === '\"1\"' || found === \"'1'\"\n        ? 'Unquote the version value: use `version: 1`, not `version: \"1\"`'\n        : 'This manifest targets a newer format — upgrade gitnexus, or set `version: 1`',\n      { cause: err },\n    );\n  }\n  throw err;\n}","preventionTips":["Write the version as a bare number (version: 1); never quote it.","Keep manifest version and tool version in lockstep: bump manifests only when the release notes say a new version exists.","When sharing group.yaml across a team, document which gitnexus version each manifest targets."],"tags":["yaml","configuration","validation","group","version"],"backgroundTag":"unsupported-config-version","analyzedSha":"52924ef12c2290ceee4612526a828ec4cdf2047f","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}