google-gemini/gemini-cli · error · AgentLoadError

Validation failed: ${formatZodError(result.error, 'Remote Ag

Error message

Validation failed: ${formatZodError(result.error, 'Remote Agents List')}

What it means

When the parsed frontmatter is a YAML array, the loader treats it as a remote-agents list and validates it with remoteAgentsListSchema. formatZodError expands every zod issue with field paths, so the message lists exactly which entries failed. Only an array takes this branch; a single object goes to the Agent Definition schema instead.

Source

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

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

  const result = markdownFrontmatterSchema.safeParse(rawFrontmatter);

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

View on GitHub (pinned to 5024443c72)

Solutions

1. Read the formatted issues and fix each named field path in the listed entries.
2. Ensure every array element has the required remote-agent fields (typically name, description, agent_card_url or agent_card_json).
3. If only one agent is intended, use a single YAML object instead of an array.
4. Cross-check against an existing working remote-agents file in the repo.

Example fix

# before
- name: svc-a
- agent_card_url: https://a.example/.well-known/agent-card.json  # missing name on this entry is fine; entry 1 missing url

# after
- name: svc-a
  agent_card_url: https://a.example/.well-known/agent-card.json

import { remoteAgentsListSchema } from './agentLoader.js';
const parsed = remoteAgentsListSchema.safeParse(yamlArray);
if (!parsed.success) {
  throw new Error(formatZodError(parsed.error, 'Pre-check Remote Agents List'));
}

When it happens

Trigger: An array whose elements are missing required fields (e.g. name, agent_card_url); mixed shapes where some entries are local-only fields; an array of strings instead of objects; a list intended for a different tool's format.

Common situations: Converting a single-agent file to a multi-remote list but leaving local-only keys in; copy-pasting a remote-agents example that omits required fields; an entry whose agent_card_url is empty or non-string.

Related errors

• Validation failed: ${formatZodError(result.error, 'Agent Def
• Unexpected state: neither agent_card_json nor agent_card_url
• Invalid taskId: ${taskId}
• Security violation: Null byte detected in path.
• Security violation: The path "${trimmedPath}" is outside the

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