--- title: Common YAML front matter errors and how to fix them slug: yaml-front-matter-errors excerpt: Most broken YAML front matter comes from a short list of mistakes. Here is how to find the bad line, then fix colons, comments, tabs, indentation, quotes and values that change type. quickAnswer: To fix invalid YAML front matter, first check that the block starts on line 1 with three dashes and ends with a second line of three dashes. Most tools expect exactly that. Then go to the line number in the error. The usual causes are a colon and a space inside a value, a tab used for indentation, a list item indented differently from its neighbors, or a value that starts with a special character. Quote values that contain a colon followed by a space or start with a special character. Replace indentation tabs with spaces, and line up list items. keyTakeaways: - Check the two dash lines first. Most tools want the opening one on line 1 and a closing one after the last field. - A colon followed by a space inside a value breaks the line. Quote the value. - A space followed by a hash sign starts a comment and silently cuts the value short. - Tabs are not allowed for indentation, and list items must line up with each other. - Some values parse without an error but change type, such as yes, no, dates and ids with leading zeros. publishedDate: 2026-10-06 dateModified: 2026-10-06 author: Bobby Huang cluster: E role: post status: published faq: - q: Should I use single or double quotes in YAML front matter? a: Either works for most text. Use single quotes for values with backslashes, such as Windows paths, because single quotes do not treat a backslash as an escape. Use double quotes when the value contains an apostrophe, or double the apostrophe inside single quotes. - q: Why does my front matter parse but show the wrong value? a: The value was read as a different type. Under YAML 1.1 rules, yes and no become booleans and unquoted dates can become date objects. A space and a hash sign also start a comment. Quote the value to keep it as text. - q: How do I check front matter without building the whole site? a: Run the block through any YAML parser. The error message gives a line and column, which points you to the line to fix. related: - yaml-front-matter-in-markdown - what-is-an-agent-handoff-file --- AI coding agents write YAML headers on a lot of Markdown files: handoffs, plans, receipts. Most of the time they parse. When one does not, your build fails, your Markdown viewer shows raw text, or a script reads the wrong status. This page lists the errors that cause most broken headers, with a broken example and a fixed one for each. For the basics of how front matter works, start with the [YAML front matter guide](yaml-front-matter-in-markdown.md). ## How to find the bad line 1. **Check line 1.** For broad compatibility, the file starts with `---`, with nothing above it, not even a blank line. Check your tool's rules: Pandoc, for one, also accepts a metadata block later in the file. 2. **Check the closing line.** Close the block with a second `---` on its own line after the last field. Pandoc also accepts `...` here, but `---` works in more places. 3. **Parse the block on its own.** If you have Python and the PyYAML package, this prints the parsed header or an error with a line number: ``` python3 -c "import sys, yaml; print(yaml.safe_load(open(sys.argv[1]).read().split('---', 2)[1]))" HANDOFF.md ``` The line numbers in the error match the file's own line numbers. This one-liner assumes the file starts with `---` and that no value contains `---`. PyYAML follows YAML 1.1, so it also shows you which values turn into booleans or dates. 4. **Go to the line in the error, then look one line up.** YAML often notices a problem one line after it starts. ## Error 1: a colon inside a value ```yaml title: Fix: login loop ``` A colon followed by a space tells YAML a new key starts. Here that happens in the middle of a value, so the line fails. Quote the whole value: ```yaml title: "Fix: login loop" ``` A colon with no space after it is fine. `url: https://example.com/docs` parses as one string. ## Error 2: a hash sign that cuts the value short ```yaml next: review PR #42 ``` This one parses with no error, which makes it worse. A space followed by `#` starts a comment, so the value is just `review PR`. Quote it: ```yaml next: "review PR #42" ``` ## Error 3: a value that starts with a special character ```yaml owner: @jane-doe title: [Draft] Migration plan ``` Some characters mean something at the start of a value. `[` and `{` start a list or a map. `*` and `&` mark aliases and anchors. `@` and the backtick are reserved. Quote any value that starts with one of them: ```yaml owner: "@jane-doe" title: "[Draft] Migration plan" ``` ## Error 4: tabs used for indentation The YAML spec does not allow tabs for indentation. A tab before a list item or a nested key often looks fine in an editor and still fails. Replace tabs with spaces. Two spaces per level is the common choice. ## Error 5: list items that do not line up ```yaml tags: - ui - settings ``` Every item in one list needs the same indent. This one may not even raise an error. The extra space can turn the second line into part of the first item, so you get one tag, `ui - settings`, instead of two. Line them up: ```yaml tags: - ui - settings ``` ## Error 6: yes, no, on and off ```yaml approved: no country: NO ``` Under YAML 1.1, unquoted `yes`, `no`, `on` and `off` are booleans, in any of their common capitalizations. Under YAML 1.2, only `true` and `false` are. A YAML 1.1 parser reads both lines above as false. Use `true` or `false` for real booleans, and quote text that happens to match: ```yaml approved: false country: "NO" ``` ## Error 7: dates and numbers that change type ```yaml date: 2026-10-06 version: 1.10 ticket: 0042 ``` YAML 1.1 parsers may turn the date into a date object. `1.10` is a number, so it becomes 1.1. `0042` loses its leading zeros, and a YAML 1.1 parser may read it as an octal number. None of these raise an error. Quote values that must stay as typed: ```yaml date: "2026-10-06" version: "1.10" ticket: "0042" ``` > Dates are the judgment call. Some tools want a real date to sort on. If a tool reads the header, check what it expects before you quote dates everywhere. ## Error 8: backslashes and apostrophes inside quotes ```yaml path: "C:\Users\jane-doe\docs" note: 'Jane's draft' ``` Inside double quotes, a backslash starts an escape. `\U` starts an 8-digit Unicode escape and `\j` is not an escape at all, so the first line fails. A path like `"C:\new"` is worse: it parses with no error, because `\n` becomes a line break. Inside single quotes, an apostrophe ends the string, so the second line fails too. Swap the quote styles, or double the apostrophe: ```yaml path: 'C:\Users\jane-doe\docs' note: "Jane's draft" ``` ## Error 9: the same key twice ```yaml status: draft owner: Jane Doe status: published ``` Keys must be unique in YAML. Parsers handle a repeat differently. Some stop with an error. Others keep the last value without a warning. Agents that update a header by appending lines can cause this. Delete the stale line. ## A habit that prevents most of this Ask your agent to quote every string value in its headers and to use `true` and `false` for booleans. The header gets a little noisier and a lot more predictable. If you review a lot of [handoff files](what-is-an-agent-handoff-file.md), a consistent header also makes the status and owner faster to find. ## Where Skimmark fits Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. Planned for v1: a Frontmatter Table that shows the YAML header as key and value rows, so you can read the fields an agent wrote without scanning raw YAML. The app itself has no AI features. To see what Skimmark is and follow along, visit [skimmark.com](https://www.skimmark.com/).