continuedev/continue · error · Error

Invalid agent file frontmatter: ${errorDetails}

Error message

Invalid agent file frontmatter: ${errorDetails}

What it means

parseAgentFile validates frontmatter with agentFileFrontmatterSchema via safeParse; on failure it joins all issue paths and messages into one descriptive error. 'name' exists but other fields are invalid.

Source

Thrown at packages/config-yaml/src/markdown/agentFiles.ts:63

 * Parses and validates an agent file from markdown content
 * Agent files must have frontmatter with at least a name
 */
export function parseAgentFile(content: string): AgentFile {
  const { frontmatter, markdown } = parseMarkdownRule(content);

  if (!frontmatter.name) {
    throw new Error(
      "Agent file must contain YAML frontmatter with a 'name' field",
    );
  }

  const validationResult = agentFileFrontmatterSchema.safeParse(frontmatter);

  if (!validationResult.success) {
    const errorDetails = validationResult.error.issues
      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
      .join(", ");
    throw new Error(`Invalid agent file frontmatter: ${errorDetails}`);
  }

  return {
    ...validationResult.data,
    prompt: markdown,
  };
}

/**
 * Serializes an Agent file back to markdown with YAML frontmatter
 */
export function serializeAgentFile(agentFile: AgentFile): string {
  const { prompt, ...frontmatter } = agentFile;

  // Filter out undefined values from frontmatter
  const cleanFrontmatter = Object.fromEntries(
    Object.entries(frontmatter).filter(([, value]) => value !== undefined),
  );

View on GitHub (pinned to 5522c6f44c)

Solutions

1. Read the message: each 'path: message' pair names the exact bad field
2. Fix or remove the listed fields
3. Regenerate frontmatter from a known-valid example for the current version

Example fix

# before
---
name: a
tools: tool1
---
# after
---
name: a
tools:
  - tool1
---

import { agentFileFrontmatterSchema } from '...';
const fm = parseMarkdownRule(content).frontmatter;
const r = agentFileFrontmatterSchema.safeParse(fm);
if (!r.success) console.log(r.error.issues);

try { parseAgentFile(content); } catch (e) { if (e.message.startsWith('Invalid agent file frontmatter')) { /* show field list */ } }

When it happens

Trigger: Frontmatter with a 'name' but invalid types/values for other fields — e.g. tools not a list, description not a string, unknown field constraints per the schema.

Common situations: Schema evolution adding stricter field validation after an upgrade, hand-edited frontmatter with wrong YAML types (string vs list).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Agent file must contain YAML frontmatter with a 'name' field
• Failed to parse config: ${formatZodError(e)}
• Failed to parse block: ${formatZodError(e)}
• Table name must be in format schema.table_name, got ${tableN
• Only rule files can be deleted

AI-assisted analysis of continuedev/continue@5522c6f44c (2026-08-27). Data as JSON: /api/errors/f5549a9359a9cdbe. Report an issue: GitHub.