google-gemini/gemini-cli · error · AgentLoadError

Validation failed: ${formatZodError(result.error, 'Agent Def

Error message

Validation failed: ${formatZodError(result.error, 'Agent Definition', rawFrontmatter)}

What it means

The non-array frontmatter branch validates against markdownFrontmatterSchema, which is the union of local and remote agent definitions. formatZodError receives the raw frontmatter so it can show the value alongside the issue, and it filters union branches by intended kind so only the relevant errors appear. A failure means no union branch matched.

Source

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

  // 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',
    }));
  }

  const result = markdownFrontmatterSchema.safeParse(rawFrontmatter);

  if (!result.success) {
    throw new AgentLoadError(
      filePath,
      `Validation failed: ${formatZodError(result.error, 'Agent Definition', rawFrontmatter)}`,
    );
  }

  const frontmatter = result.data;

  if (frontmatter.kind === 'remote') {
    return [
      {
        ...frontmatter,
        kind: 'remote',
      },
    ];
  }

  // Construct the local agent definition
  return [

View on GitHub (pinned to 5024443c72)

Solutions

Read the formatted output: it lists each path, the bad value, and the constraint.
Add the required 'name' field if missing.
Remove unknown keys or move them under a supported extension point.
Match the field types and enum values documented in markdownFrontmatterSchema.

Example fix

# before
---
name: my-agent
discription: typo here   # unknown key; description missing
---

# after
---
name: my-agent
description: Correctly named field
---

Defensive patterns

Strategy: validation

Validate before calling

import { markdownFrontmatterSchema } from './agentLoader.js';
const parsed = markdownFrontmatterSchema.safeParse(rawFrontmatter);
if (!parsed.success) {
  throw new Error(formatZodError(parsed.error, 'Pre-check Agent Definition', rawFrontmatter));
}

Prevention

Run frontmatter through the zod schema during authoring.
Keep a working agent file as a structural reference.
Watch for typos in required keys (name, description).

When it happens

Trigger: Missing required field 'name'; unknown top-level key not allowed by either branch; a field with the wrong type (e.g. model as a number); a remote agent missing both agent_card_json and agent_card_url caught at the schema level; an enum value outside the allowed set (e.g. auth.type).

Common situations: Renaming a supported key and forgetting to update dependent files; adding an experimental field not yet in the schema; version skew between the loader and the agent file format; typos in keys (e.g. discription vs description) that zod reports as unknown keys or missing required.

Related errors

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