{"record":{"id":"f4efcc93d83fef8e","repo":"google-gemini/gemini-cli","slug":"validation-failed-formatzoderror-result-error-f4efcc","errorCode":null,"errorMessage":"Validation failed: ${formatZodError(result.error, 'Agent Definition', rawFrontmatter)}","messagePattern":"Validation failed: (.+?)","errorType":"validation","errorClass":"AgentLoadError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/agentLoader.ts","lineNumber":387,"sourceCode":"  // 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  }\n\n  const frontmatter = result.data;\n\n  if (frontmatter.kind === 'remote') {\n    return [\n      {\n        ...frontmatter,\n        kind: 'remote',\n      },\n    ];\n  }\n\n  // Construct the local agent definition\n  return [","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agentLoader.ts#L369-L405","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\n---\nname: my-agent\ndiscription: typo here   # unknown key; description missing\n---\n\n# after\n---\nname: my-agent\ndescription: Correctly named field\n---","handlingStrategy":"validation","validationCode":"import { markdownFrontmatterSchema } from './agentLoader.js';\nconst parsed = markdownFrontmatterSchema.safeParse(rawFrontmatter);\nif (!parsed.success) {\n  throw new Error(formatZodError(parsed.error, 'Pre-check Agent Definition', rawFrontmatter));\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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)."],"tags":["agent-loader","zod","validation","schema"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}