abhigyanpatwari/GitNexus · error · Error

Invalid YAML: expected an object

Error message

Invalid YAML: expected an object

What it means

Thrown by parseGroupConfig when js-yaml's load() returns a value that is not a plain object — i.e. the YAML parsed to null, a scalar (string/number), or an array at the top level. group.yaml must be a YAML mapping (key/value document). The check runs before any field validation, so it catches fundamentally malformed manifests.

Source

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

  shared_libs: true,
  embedding_fallback: true,
  includes: false,
  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)) {

View on GitHub (pinned to d540b00184)

Solutions

1. Open group.yaml and confirm the top level is a mapping — it should start with keys like 'version:', 'name:', 'repos:', not with '-' (array) or a bare scalar.
2. If the file is empty or contains only whitespace/fragments, regenerate it with createGroupDir (which writes a valid template).
3. Validate the YAML with an external parser (e.g. `npx js-yaml group.yaml`) to confirm it parses to an object.

Example fix

// before — top-level array, parseGroupConfig rejects
- version: 1
- name: mygroup

// after — top-level mapping
version: 1
name: mygroup
repos: {}
links: []

import * as yaml from 'js-yaml';
function isValidGroupManifestDoc(text: string): boolean {
  let parsed: unknown;
  try { parsed = yaml.load(text, { schema: yaml.JSON_SCHEMA }); }
  catch { return false; }
  return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);
}
// call before parseGroupConfig:
if (!isValidGroupManifestDoc(yamlContent)) {
  throw new Error('group.yaml must parse to a YAML mapping — refusing to load');
}

function isPlainObject(v: unknown): v is Record<string, unknown> {
  return v !== null && typeof v === 'object' && !Array.isArray(v);
}

When it happens

Trigger: Loading a group.yaml that is a bare scalar (e.g. contents are just "version: 1" with no surrounding mapping, or a single quoted string), a YAML array at the top level (e.g. starts with '- '), or empty/null content that js-yaml returns null for.

Common situations: Hand-edited group.yaml that lost its top-level structure; a YAML file generated as a list of entries instead of a mapping; a file that is actually a different format (JSON array, plain text) misnamed group.yaml; a truncation/corruption that left only a fragment.

Related errors

• version is required in group.yaml
• 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/c3413814a3b9636d. Report an issue: GitHub.