can1357/oh-my-pi · error · AgentParsingError

Invalid agent field: ${filePath}\n${content}

Error message

Invalid agent field: ${filePath}\n${content}

What it means

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.

Source

Thrown at packages/coding-agent/src/task/agents.ts:118

	}
}

/**
 * Parse an agent from embedded content.
 */
export function parseAgent(
	filePath: string,
	content: string,
	source: AgentSource,
	level: "fatal" | "warn" | "off" = "fatal",
): AgentDefinition {
	const { frontmatter, body } = parseFrontmatter(content, {
		location: filePath,
		level,
	});
	const fields = parseAgentFields(frontmatter);
	if (!fields) {
		throw new AgentParsingError(new Error(`Invalid agent field: ${filePath}\n${content}`), filePath);
	}
	return {
		...fields,
		systemPrompt: body,
		source,
		filePath,
	};
}

/** Cache for bundled agents */
let bundledAgentsCache: AgentDefinition[] | null = null;

/**
 * Load all bundled agents from embedded content.
 * Results are cached after first load.
 */
export function loadBundledAgents(): AgentDefinition[] {
	if (bundledAgentsCache !== null) {

View on GitHub (pinned to 9690622007)

Solutions

1. Open the filePath in the message and fix the frontmatter to include all required agent fields with correct types.
2. Validate the YAML frontmatter syntax (indentation, colons, quoting).
3. Compare against a working bundled agent file and mirror its field structure.
4. If the file is a leftover from an older version, update it to the current schema or delete it.

Example fix

// before (my-agent.md)
---
name: my-agent
---
// after
---
name: my-agent
description: Does things when asked
mode: subagent
---

import fm from "front-matter";
const { attributes } = fm<any>(content);
if (!attributes.name || !attributes.description) {
  throw new Error(`agent file ${filePath} needs name + description frontmatter`);
}

function hasRequiredAgentFields(v: unknown): v is { name: string; description: string } {
  return typeof v === "object" && v !== null &&
    typeof (v as any).name === "string" && typeof (v as any).description === "string";
}

try {
  const agent = parseAgent(content, filePath, source);
} catch (err) {
  if (err instanceof AgentParsingError) {
    logger.warn("Skipping invalid agent file", { filePath: err.filePath });
    return null; // skip bad file instead of failing the whole directory load
  }
  throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Config overlay must be a YAML mapping: ${filePath}
• Failed to load tree-sitter language: {err}
• Destination option ${key} must be a string
• Destination option ${key} must be a finite number
• Destination option ${key} must be a boolean

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/ec76f3155ea905f2. Report an issue: GitHub.