{"record":{"id":"de1ebb1c5557c994","repo":"google-gemini/gemini-cli","slug":"validation-failed-formatzoderror-result-error","errorCode":null,"errorMessage":"Validation failed: ${formatZodError(result.error, 'Remote Agents List')}","messagePattern":"Validation failed: (.+?)","errorType":"validation","errorClass":"AgentLoadError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/agentLoader.ts","lineNumber":373,"sourceCode":"\n  const frontmatterStr = match[1];\n  const body = match[2] || '';\n\n  let rawFrontmatter: unknown;\n  try {\n    rawFrontmatter = load(frontmatterStr);\n  } catch (error) {\n    throw new AgentLoadError(\n      filePath,\n      `YAML frontmatter parsing failed: ${getErrorMessage(error)}`,\n    );\n  }\n\n  // Handle array of remote agents\n  if (Array.isArray(rawFrontmatter)) {\n    const result = remoteAgentsListSchema.safeParse(rawFrontmatter);\n    if (!result.success) {\n      throw new AgentLoadError(\n        filePath,\n        `Validation failed: ${formatZodError(result.error, 'Remote Agents List')}`,\n      );\n    }\n    return result.data.map((agent) => ({\n      ...agent,\n      kind: 'remote',\n    }));\n  }\n\n  const result = markdownFrontmatterSchema.safeParse(rawFrontmatter);\n\n  if (!result.success) {\n    throw new AgentLoadError(\n      filePath,\n      `Validation failed: ${formatZodError(result.error, 'Agent Definition', rawFrontmatter)}`,\n    );\n  }","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agentLoader.ts#L355-L391","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the formatted issues and fix each named field path in the listed entries.","Ensure every array element has the required remote-agent fields (typically name, description, agent_card_url or agent_card_json).","If only one agent is intended, use a single YAML object instead of an array.","Cross-check against an existing working remote-agents file in the repo."],"exampleFix":"# before\n- name: svc-a\n- agent_card_url: https://a.example/.well-known/agent-card.json  # missing name on this entry is fine; entry 1 missing url\n\n# after\n- name: svc-a\n  agent_card_url: https://a.example/.well-known/agent-card.json","handlingStrategy":"validation","validationCode":"import { remoteAgentsListSchema } from './agentLoader.js';\nconst parsed = remoteAgentsListSchema.safeParse(yamlArray);\nif (!parsed.success) {\n  throw new Error(formatZodError(parsed.error, 'Pre-check Remote Agents List'));\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate the list with the schema before pointing the loader at it.","Keep one example remote-agents file as a reference shape.","Ensure every entry has name and a card url/json."],"tags":["agent-loader","zod","validation","remote-agent"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}