komal.nakrani
Browse Themes
ThemesCategoriesDocsBlogTips & Tricks
Content & MDX••By Komal Nakrani

Fix: Failed to Parse Markdown Frontmatter in Astro

Astro's 'Failed to parse Markdown frontmatter' is a YAML syntax error: unquoted colons, tabs, bad indentation or mismatched quotes. Fix each.

#Astro#Errors#Markdown#YAML

Astro shows “Failed to parse Markdown frontmatter” when the YAML between the --- lines at the top of a Markdown or MDX file isn’t valid YAML. This happens before any schema check, so it’s a syntax problem, not a content problem. Astro points to the file and usually the line. The most common causes are an unquoted colon in a title, tabs instead of spaces, and broken indentation in lists.

Key Takeaways

  • Quote any value containing a colon followed by a space, a #, or leading special characters.
  • YAML forbids tabs for indentation; use spaces.
  • The opening and closing --- must be on their own lines, with nothing before the first one.
  • A missing closing quote breaks every line after it.

Unquoted colons

# Wrong: the second colon starts a new key
title: Astro vs Next.js: Which to Choose

# Right
title: "Astro vs Next.js: Which to Choose"

This is by far the most common cause in blog titles.

Hash characters

# Wrong: everything after # is a comment
description: Use #astro on social posts

# Right
description: "Use #astro on social posts"

Quotes inside quotes

# Wrong
title: "The "zero JS" myth"

# Right: switch the outer quotes, or escape
title: 'The "zero JS" myth'
title: "The \"zero JS\" myth"

Inside single quotes, write an apostrophe as two single quotes: 'Astro''s best features'.

Tabs and indentation

tags:
	- astro      # a tab: invalid
  - astro      # two spaces: valid

Set your editor to insert spaces in Markdown files. Nested keys must line up exactly.

Delimiters

The frontmatter must start on the first line of the file:

---
title: "Hello"
---

Body text.

A blank line or a byte-order mark before the first ---, or a closing --- with trailing characters, breaks parsing. Some editors add a BOM silently; re-save the file as UTF-8 without BOM.

Multi-line text

description: >
  A long description that wraps
  across several lines in the file.

> folds lines into one; | keeps line breaks.

Find the problem quickly

Paste the frontmatter into any YAML validator, or check it with Node:

node -e "require('yaml').parse(require('fs').readFileSync('src/content/blog/post.md','utf8').split('---')[1])"

(yaml is usually already installed as a dependency of Astro tooling; otherwise npm i -D yaml.)

Once the YAML parses, values are checked against your schema; see Frontmatter does not match collection schema. Content structure is covered in the Astro content collections guide, and the content docs for Komal themes list each theme’s fields. For YAML rules, the Astro Markdown guide links to the spec.

FAQ

Should I quote every frontmatter string?

Quoting titles and descriptions is a good habit; it avoids colon and # problems entirely.

Does MDX use the same frontmatter rules?

Yes. MDX frontmatter is YAML too.