google-gemini/gemini-cli · error · AgentLoadError

YAML frontmatter parsing failed: ${getErrorMessage(error)}

Error message

YAML frontmatter parsing failed: ${getErrorMessage(error)}

What it means

After the frontmatter block is extracted, YAML.load parses it; any YAML syntax error (bad indentation, tabs, unquoted special characters, duplicate keys) is wrapped in AgentLoadError with the parser's message. This isolates structural YAML problems from semantic validation, which runs later via zod.

Source

Thrown at packages/core/src/agents/agentLoader.ts:363

  }

  // Split frontmatter and body
  const match = fileContent.match(FRONTMATTER_REGEX);
  if (!match) {
    throw new AgentLoadError(
      filePath,
      'Invalid agent definition: Missing mandatory YAML frontmatter. Agent Markdown files MUST start with YAML frontmatter enclosed in triple-dashes "---" (e.g., ---\nname: my-agent\n---).',
    );
  }

  const frontmatterStr = match[1];
  const body = match[2] || '';

  let rawFrontmatter: unknown;
  try {
    rawFrontmatter = load(frontmatterStr);
  } catch (error) {
    throw new AgentLoadError(
      filePath,
      `YAML frontmatter parsing failed: ${getErrorMessage(error)}`,
    );
  }

  // Handle array of remote agents
  if (Array.isArray(rawFrontmatter)) {
    const result = remoteAgentsListSchema.safeParse(rawFrontmatter);
    if (!result.success) {
      throw new AgentLoadError(
        filePath,
        `Validation failed: ${formatZodError(result.error, 'Remote Agents List')}`,
      );
    }
    return result.data.map((agent) => ({
      ...agent,
      kind: 'remote',
    }));

View on GitHub (pinned to 5024443c72)

Solutions

1. Run a YAML linter (e.g. yamllint or an IDE YAML plugin) on the frontmatter block.
2. Replace tabs with spaces and align indentation consistently (2 spaces is typical).
3. Quote any value containing ': ', '#', or leading '{', '[', '&', '*'.
4. Validate locally with js-yaml load() before pointing the loader at the file.

Example fix

# before (tab-indented, breaks YAML)
---
name: my-agent
	description: tab-indented
---

# after
---
name: my-agent
description: space-indented
---

import { load } from 'js-yaml';
try {
  load(frontmatterStr);
} catch (e) {
  throw new Error(`Frontmatter YAML is invalid: ${getErrorMessage(e)}`);
}

try {
  return await parseAgentMarkdown(filePath);
} catch (e) {
  if (e instanceof AgentLoadError && /YAML frontmatter parsing failed/.test(e.message)) {
    // surface the parser line/col to the author
  }
  throw e;
}

When it happens

Trigger: Mixed tabs and spaces in indentation; a value like 'name: # todo' where '#' starts an unintended comment; unquoted strings containing ': ' or leading special chars; trailing colons with no value; YAML aliases to undefined anchors.

Common situations: Hand-editing frontmatter without a YAML-aware editor; copying frontmatter from a richer YAML doc that used anchors; tabs inserted by an editor configured for tabs; locale-specific quote characters.

Related errors

• Invalid agent definition: Missing mandatory YAML frontmatter
• Invalid syntax${contextInfo}: Unclosed injection starting at
• Invalid retention period format: ${period}. Expected format:
• Failed to load session data
• Could not read file: ${getErrorMessage(error)}

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/d2e30585af8d1d9a. Report an issue: GitHub.