{"record":{"id":"ec76f3155ea905f2","repo":"can1357/oh-my-pi","slug":"invalid-agent-field-filepath-n-content","errorCode":null,"errorMessage":"Invalid agent field: ${filePath}\\n${content}","messagePattern":"Invalid agent field: (.+?)\\\\n(.+?)","errorType":"validation","errorClass":"AgentParsingError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/task/agents.ts","lineNumber":118,"sourceCode":"\t}\n}\n\n/**\n * Parse an agent from embedded content.\n */\nexport function parseAgent(\n\tfilePath: string,\n\tcontent: string,\n\tsource: AgentSource,\n\tlevel: \"fatal\" | \"warn\" | \"off\" = \"fatal\",\n): AgentDefinition {\n\tconst { frontmatter, body } = parseFrontmatter(content, {\n\t\tlocation: filePath,\n\t\tlevel,\n\t});\n\tconst fields = parseAgentFields(frontmatter);\n\tif (!fields) {\n\t\tthrow new AgentParsingError(new Error(`Invalid agent field: ${filePath}\\n${content}`), filePath);\n\t}\n\treturn {\n\t\t...fields,\n\t\tsystemPrompt: body,\n\t\tsource,\n\t\tfilePath,\n\t};\n}\n\n/** Cache for bundled agents */\nlet bundledAgentsCache: AgentDefinition[] | null = null;\n\n/**\n * Load all bundled agents from embedded content.\n * Results are cached after first load.\n */\nexport function loadBundledAgents(): AgentDefinition[] {\n\tif (bundledAgentsCache !== null) {","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/task/agents.ts#L100-L136","documentation":"parseAgent parses an agent definition markdown file: frontmatter is extracted and passed through parseAgentFields, which returns null when required fields are missing or invalid. The error wraps the file path and full content in an AgentParsingError so the offending definition is visible. Bundled and user agent files are both parsed this way.","triggerScenarios":"loadBundledAgents or the user agents-directory loader reads an agent .md file whose frontmatter fails parseAgentFields (missing required field like description/mode, wrong type, malformed YAML key), yielding fields === null.","commonSituations":"Hand-edited agent files in ~/.config/.../agents/ with a typo'd or absent required frontmatter key, YAML indentation mistakes, copying an agent template and leaving placeholders, or a renamed frontmatter field after an upgrade.","solutions":["Open the filePath in the message and fix the frontmatter to include all required agent fields with correct types.","Validate the YAML frontmatter syntax (indentation, colons, quoting).","Compare against a working bundled agent file and mirror its field structure.","If the file is a leftover from an older version, update it to the current schema or delete it."],"exampleFix":"// before (my-agent.md)\n---\nname: my-agent\n---\n// after\n---\nname: my-agent\ndescription: Does things when asked\nmode: subagent\n---","handlingStrategy":"validation","validationCode":"import fm from \"front-matter\";\nconst { attributes } = fm<any>(content);\nif (!attributes.name || !attributes.description) {\n  throw new Error(`agent file ${filePath} needs name + description frontmatter`);\n}","typeGuard":"function hasRequiredAgentFields(v: unknown): v is { name: string; description: string } {\n  return typeof v === \"object\" && v !== null &&\n    typeof (v as any).name === \"string\" && typeof (v as any).description === \"string\";\n}","tryCatchPattern":"try {\n  const agent = parseAgent(content, filePath, source);\n} catch (err) {\n  if (err instanceof AgentParsingError) {\n    logger.warn(\"Skipping invalid agent file\", { filePath: err.filePath });\n    return null; // skip bad file instead of failing the whole directory load\n  }\n  throw err;\n}","preventionTips":["Start new agent files by copying a known-good bundled agent as a template.","Validate frontmatter in your editor with a YAML linter.","After upgrades, diff your custom agents against the current agent schema.","Keep one agent per file and avoid placeholder values like TODO."],"tags":["config","yaml","frontmatter","agents","validation"],"backgroundTag":"invalid-agent-frontmatter","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}