# Atlas error: Failed to parse YAML frontmatter in an agent or command markdown file > Open the markdown file named in the message and fix the YAML block between the `---` fences, checking for tabs, an unquoted colon, or a missing closing fence. Atlas exits with : Failed to parse YAML frontmatter: because config/markdown.ts parses the YAML frontmatter of markdown-defined agents, commands, and skills, and re-throws any YAML error as ConfigFrontmatterError carrying the file path and the underlying parser message. The fix is to open the markdown file named in the message and repair the YAML block between the `---` fences. The common causes are tabs used for indentation, an unquoted value containing a colon, or a missing closing fence. ## Symptom Atlas exits with: : Failed to parse YAML frontmatter: . The path names the markdown file, and the trailing text is the underlying YAML parser message, printed verbatim by the CLI formatter. ## Cause config/markdown.ts parses the YAML frontmatter of markdown-defined agents, commands, and skills. Any YAML error from that parse is re-thrown as ConfigFrontmatterError, carrying the file path and the underlying parser message, so Atlas refuses to start until the frontmatter is valid YAML. ## Fix 1. Open the markdown file named in the message and fix the YAML block between the `---` fences. 2. Check the common causes: tabs used for indentation, an unquoted value containing a colon, or a missing closing fence. 3. Replace any tab characters in the frontmatter with spaces, since YAML rejects tabs for indentation. 4. Validate the frontmatter in isolation with any YAML linter. 5. Re-run Atlas, because the frontmatter error message is printed verbatim by the CLI formatter, so a remaining error will name the same file. ## Why does Atlas say Failed to parse YAML frontmatter? Atlas prints : Failed to parse YAML frontmatter: because config/markdown.ts parses the YAML block between the 2 `---` fences in markdown-defined agents, commands, and skills. Any YAML error there is re-thrown as ConfigFrontmatterError, carrying both the file path and the underlying parser message. Agents, commands, and skills in Atlas can be defined in markdown, and the metadata for each one lives in a YAML frontmatter block at the top of the file. config/markdown.ts parses that block. When the YAML parser rejects it, Atlas does not swallow the parser's complaint or replace it with something vaguer. ConfigFrontmatterError carries both the file path and the underlying parser message, which is why the error you see has two useful halves: which file broke, and what the YAML parser actually objected to. ## How to fix the YAML frontmatter error in Atlas Fix the Atlas frontmatter error by opening the markdown file named in the message and repairing the YAML between the `---` fences. Atlas documents 3 common causes: tabs used for indentation, an unquoted value containing a colon, and a missing closing fence. Check those first. Start with the fences. The frontmatter block is delimited by `---` at the top and `---` at the bottom, and a missing closing fence means the YAML parser keeps reading into the markdown body, where it will find something it cannot parse. Next check indentation: YAML does not accept tab characters for indentation, and an editor that inserts tabs will produce a frontmatter block that looks correct and parses as garbage. Last, look for an unquoted value containing a colon, since YAML reads the colon as a key separator and the line collapses into nonsense. ## Why do tabs break YAML frontmatter in Atlas agents? Tabs break Atlas YAML frontmatter because YAML rejects tab characters for indentation, and config/markdown.ts re-throws that rejection as ConfigFrontmatterError with the parser's message. Tabs are 1 of the 3 documented causes, alongside an unquoted colon and a missing closing fence. Replace every tab with spaces. Tab indentation is the hardest of the three to see, because most editors render a tab and a run of spaces identically. The YAML parser does not. Turn on whitespace rendering, or configure the editor to insert spaces, and re-indent the frontmatter block of the agent or command markdown file that Atlas named. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so a broken agent definition is worth fixing properly rather than working around, since the agents you define are the ones doing the work. ## Why does an unquoted colon break the frontmatter? An unquoted value containing a colon breaks Atlas frontmatter because YAML reads a colon as a key separator, giving 2 separators on 1 line. config/markdown.ts hands the block to the YAML parser, and Atlas re-throws the parser's complaint as ConfigFrontmatterError naming the file path. Descriptions are where this bites. A description field that contains a colon, for example a sentence with a clause introduced by a colon, is parsed as though the text after the colon were a nested value. Quoting the whole value resolves it: wrap the value in quotes and the YAML parser treats the colon as ordinary text. The error message from the parser, which Atlas passes through verbatim, usually points at the offending line, so read the portion of the message rather than skimming past it to the file path. ## How to validate Atlas frontmatter before running Atlas Validate Atlas frontmatter in isolation with any YAML linter, which is step 3 of the documented fix. Copying the block between the `---` fences into a linter reproduces exactly what config/markdown.ts does, so the linter's complaint is the one Atlas will re-throw as ConfigFrontmatterError. Linting in isolation is the documented step, and it shortens the loop considerably. Copy only the content between the opening `---` and the closing `---`, not the markdown body, into any YAML linter. If the linter accepts it, config/markdown.ts will too. If the linter rejects it, you have the same underlying parser message Atlas would print, without restarting Atlas to get it. Fix, lint, and only then re-run Atlas. The caveat is honest: a linter validates YAML syntax, not whether the fields you wrote are the ones Atlas expects. ## How to verify the frontmatter fix worked in Atlas Verify the Atlas frontmatter fix by re-running Atlas, the 4th and last documented step. A start with no Failed to parse YAML frontmatter message means config/markdown.ts parsed the block between the `---` fences and the markdown-defined agent, command, or skill loaded. Re-running Atlas is the verification, because the frontmatter error message is printed verbatim by the CLI formatter, so any remaining YAML problem will name the same file path and the same underlying parser complaint. If the error persists with an identical , the edit did not land in the file Atlas is reading, so check the path in the message. If the error changes, progress has been made and the parser has moved on to the next problem in the block. ## FAQ ### How do I fix Failed to parse YAML frontmatter in Atlas? Open the markdown file named in the message and fix the YAML block between the `---` fences. Check for tabs used for indentation, an unquoted value containing a colon, or a missing closing fence, then re-run Atlas. ### What is ConfigFrontmatterError in Atlas? ConfigFrontmatterError is what config/markdown.ts re-throws when the YAML frontmatter of a markdown-defined agent, command, or skill fails to parse. It carries the file path and the underlying parser message, which the CLI formatter prints verbatim. ### Can I use tabs in Atlas agent frontmatter? No. Tabs used for indentation are one of the documented causes of the Atlas frontmatter parse failure, because YAML does not accept tab indentation. Replace tabs with spaces inside the block between the `---` fences. ### Why does a colon break my Atlas command frontmatter? YAML reads a colon as a key separator, so an unquoted value containing a colon fails to parse and config/markdown.ts re-throws the error. Quote the whole value so the YAML parser treats the colon as ordinary text. ### How do I check Atlas frontmatter without starting Atlas? Validate the frontmatter in isolation with any YAML linter. Copy the block between the opening and closing `---` fences into the linter. If the linter parses it, config/markdown.ts will parse it too, though the linter cannot tell you whether the fields are the ones Atlas expects. ### Which Atlas files use YAML frontmatter? config/markdown.ts parses the YAML frontmatter of markdown-defined agents, commands, and skills. A parse failure in any of them produces : Failed to parse YAML frontmatter: , and the path names which file to open. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/agent-frontmatter-parse-failed Source of truth: aeo_pages row `/resources/troubleshooting/agent-frontmatter-parse-failed` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.