Fix: Frontmatter Does Not Match Collection Schema in Astro

Astro shows “Content entry frontmatter does not match schema” when a Markdown or MDX file’s frontmatter fails the Zod schema for its collection. This is content collections doing their job. The message names the collection, the file and each failing field, in a form like blog → launch.md followed by title: Required. Fix that field in the file, or change the schema if the rule is wrong.

Key Takeaways

• Read the field list in the error: it tells you exactly what to change and where.
• “Required” means the field is missing; “Expected string, received number” means the type is wrong.
• Make genuinely optional fields .optional() or give them a .default().
• Dates in YAML should go through z.coerce.date().

Common messages and fixes

Required

---
# title is missing
description: "Our launch announcement"
---

Add the field, or make it optional in src/content.config.ts:

title: z.string(),                    // required
subtitle: z.string().optional(),      // may be missing
draft: z.boolean().default(false),    // missing becomes false

Expected string, received number

YAML guesses types. version: 7.2 is a number; tag: 2026 is a number.

version: "7.2"

Quote values that must be strings, or coerce in the schema: z.coerce.string().

Expected date, received string

pubDate: z.coerce.date(),

z.coerce.date() accepts 2026-10-28 and full ISO strings. A plain z.date() only passes when YAML already parsed a date, which depends on formatting.

Invalid enum value

category: z.enum(['Routing', 'Styling', 'SEO']),

category: routing fails because of case. Match the enum exactly, or normalise with z.string().transform((s) => s.toLowerCase()).

Arrays

tags: astro is a string, not an array. Use either form:

tags: ["astro", "seo"]
tags:
  - astro
  - seo

Finding all the bad files at once

The build stops at the first error. To see every failing file in one go, run npx astro sync, fix, and repeat; or temporarily loosen a field with .optional(), build, and grep for entries where it’s missing.

When the schema is wrong

If a valid piece of content fails, update the schema rather than bending the content. Schemas are documentation for writers: each field should say what’s allowed.

The Astro content collections guide covers schemas, coercion and references in depth, and the content docs for Komal themes list each theme’s fields. Related: Failed to parse Markdown frontmatter is a YAML syntax error rather than a schema error. Zod’s own documentation lists every validator.

FAQ

Can I skip schema validation for one file?

No. Make the problem field optional or fix the file. Validation is what keeps broken pages out of production.

Why does the error mention a file I didn’t change?

A schema change applies to every entry. Tightening a rule surfaces older files that never met it.