{"record":{"id":"d2e30585af8d1d9a","repo":"google-gemini/gemini-cli","slug":"yaml-frontmatter-parsing-failed-geterrormessage","errorCode":null,"errorMessage":"YAML frontmatter parsing failed: ${getErrorMessage(error)}","messagePattern":"YAML frontmatter parsing failed: (.+?)","errorType":"exception","errorClass":"AgentLoadError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/agentLoader.ts","lineNumber":363,"sourceCode":"  }\n\n  // Split frontmatter and body\n  const match = fileContent.match(FRONTMATTER_REGEX);\n  if (!match) {\n    throw new AgentLoadError(\n      filePath,\n      '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---).',\n    );\n  }\n\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    }));","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/agentLoader.ts#L345-L381","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run a YAML linter (e.g. yamllint or an IDE YAML plugin) on the frontmatter block.","Replace tabs with spaces and align indentation consistently (2 spaces is typical).","Quote any value containing ': ', '#', or leading '{', '[', '&', '*'.","Validate locally with js-yaml load() before pointing the loader at the file."],"exampleFix":"# before (tab-indented, breaks YAML)\n---\nname: my-agent\n\tdescription: tab-indented\n---\n\n# after\n---\nname: my-agent\ndescription: space-indented\n---","handlingStrategy":"try-catch","validationCode":"import { load } from 'js-yaml';\ntry {\n  load(frontmatterStr);\n} catch (e) {\n  throw new Error(`Frontmatter YAML is invalid: ${getErrorMessage(e)}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await parseAgentMarkdown(filePath);\n} catch (e) {\n  if (e instanceof AgentLoadError && /YAML frontmatter parsing failed/.test(e.message)) {\n    // surface the parser line/col to the author\n  }\n  throw e;\n}","preventionTips":["Use a YAML-aware editor with schema validation on frontmatter.","Never use tabs in YAML; configure the editor for spaces.","Quote values containing ': ', '#', or leading special characters."],"tags":["agent-loader","yaml","parsing","authoring"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}