abhigyanpatwari/GitNexus · error · Error

Unsupported group.yaml version

Error message

Unsupported group.yaml version: ${raw.version}. Expected 1.

What it means

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.

Solutions

1. Set the value to the unquoted number: `version: 1`.
2. If the file legitimately uses a newer version, upgrade gitnexus to a release that supports that manifest version instead of downgrading the file.
3. Remove quotes/prefixes: "1", v1, and 1-beta all fail; plain 1 passes.

Example fix

# before (group.yaml)
version: "1"
name: my-group
# -> Error: Unsupported group.yaml version: 1 (as string). Expected 1.

# after
version: 1
name: my-group

import yaml from 'js-yaml';

export function checkGroupVersion(content: string): void {
  const doc = yaml.load(content, { schema: yaml.JSON_SCHEMA }) as Record<string, unknown>;
  if (doc.version !== 1) {
    throw new Error(
      `group.yaml version must be the number 1 (unquoted); got ${JSON.stringify(doc.version)}`,
    );
  }
}

export const isSupportedGroupVersion = (v: unknown): v is 1 => v === 1;

try {
  config = await loadGroupConfig(groupDir);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unsupported group.yaml version')) {
    const found = /version: (.+?)\./.exec(err.message)?.[1];
    throw new Error(
      found === '"1"' || found === "'1'"
        ? 'Unquote the version value: use `version: 1`, not `version: "1"`'
        : 'This manifest targets a newer format — upgrade gitnexus, or set `version: 1`',
      { cause: err },
    );
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid YAML: expected an object
• links[ ].contract is required
• links[ ].from " " does not match any repo path in group
• links[ ].role " " is invalid. Expected: provider | consumer
• links[ ].to " " does not match any repo path in group

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/596e899181614c2d. Report an issue: GitHub.

Appendix: source

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

  includes: false,
  workspace_deps: false,
};

const DEFAULT_MATCHING = {
  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 reposRaw = raw.repos as Record<string, unknown>;
  const repos: Record<string, string> = {};
  for (const [memberPath, registryName] of Object.entries(reposRaw)) {
    if (typeof registryName !== 'string' || registryName.trim() === '') {
      throw new Error(
        `repos["${memberPath}"] must be a non-empty registry name string, not ${typeof registryName}`,
      );
    }
    repos[memberPath] = registryName.trim();
  }
  const repoPaths = new Set(Object.keys(repos));

View on GitHub (pinned to 52924ef12c)