abhigyanpatwari/GitNexus · error · Error

version is required in group.yaml

Error message

version is required in group.yaml

What it means

Thrown by parseGroupConfig when the parsed YAML object has no 'version' key. Version is mandatory because the parser is version-gated (it only accepts version 1) and future manifest formats will branch on this field. The check fires before name/repos validation.

Source

Thrown at gitnexus/src/core/group/config-parser.ts:53

  workspace_deps: false,
};

const DEFAULT_MATCHING = {
  bm25_threshold: 0.7,
  embedding_threshold: 0.65,
  max_candidates_per_step: 3,
  exclude_links_paths: [] as string[],
  exclude_links_param_only_paths: false,
};

export function parseGroupConfig(yamlContent: string): GroupConfig {
  const raw = yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;

  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
    throw new Error('Invalid YAML: expected an object');
  }

  if (raw.version === undefined) throw new Error('version is required in group.yaml');
  if (raw.version !== 1) {
    throw new Error(`Unsupported group.yaml version: ${raw.version}. Expected 1.`);
  }
  if (!raw.name || typeof raw.name !== 'string') throw new Error('name is required in group.yaml');
  if (!raw.repos || typeof raw.repos !== 'object' || Array.isArray(raw.repos)) {
    throw new Error('repos is required in group.yaml (must be a mapping)');
  }

  const repos = raw.repos as Record<string, string>;
  const repoPaths = new Set(Object.keys(repos));

  const rawLinks = (raw.links as unknown[]) || [];
  const links: GroupManifestLink[] = rawLinks.map((l: unknown, i: number) => {
    const link = l as Record<string, unknown>;
    if (!link.from || !repoPaths.has(link.from as string)) {
      throw new Error(`links[${i}].from "${link.from}" does not match any repo path in group`);
    }
    if (!link.to || !repoPaths.has(link.to as string)) {

View on GitHub (pinned to d540b00184)

Solutions

1. Add `version: 1` as the first key of group.yaml.
2. If unsure of the full schema, regenerate the manifest with createGroupDir which writes the correct template, then merge in your values.

Example fix

# before
name: mygroup
repos: {}

# after
version: 1
name: mygroup
repos: {}

function hasVersion1(raw: Record<string, unknown>): boolean {
  return raw.version === 1;
}
const raw = yaml.load(text, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;
if (raw.version === undefined) throw new Error('add version: 1 to group.yaml');

function hasVersion(v: unknown): v is number { return typeof v === 'number'; }

When it happens

Trigger: A group.yaml mapping that omits the top-level 'version' key entirely, or where the key is misspelled (e.g. 'Version', 'schemaVersion').

Common situations: Hand-authored group.yaml that skipped the version field; a manifest copied from an example that omitted it; a typo in the key name.

Related errors

• Invalid YAML: expected an object
• name is required in group.yaml
• repos is required in group.yaml (must be a mapping)
• links[${i}].from "${link.from}" does not match any repo path
• links[${i}].to "${link.to}" does not match any repo path in

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