Astro — content collection schema validation error

Astro build fails because a Markdown frontmatter field does not match the Zod schema defined in content.config.ts for the collection.

beginnerdebuggingastrobuild

Symptoms

Build error: "collectionName does not match the Zod schema"
The field is present in the Markdown but has the wrong type or is missing
Local dev works but production build fails

Possible causes

The frontmatter field type does not match the schema (string vs number)
A required field is missing from one or more Markdown files
The schema was updated but existing content was not migrated

Diagnosis steps

Run astro check to see schema violations

npx astro check

Interpretation

The output lists each file and field that fails validation with the expected vs actual type.

Inspect the frontmatter of the failing file

head -20 src/content/collection/failing-file.md

Interpretation

Compare the YAML frontmatter against the schema definition in content.config.ts.

Root cause

The Zod schema in content.config.ts enforces a type or required field that the Markdown frontmatter does not satisfy, causing the content loader to reject the entry at build time.

Fix

Update the frontmatter to match the schema, or adjust the schema to accept the existing data shape. If the schema changed, migrate all affected content files before rebuilding.

Verify the fix

Run astro check again and confirm zero errors, then run the build and verify the collection entry appears in the generated output.

Symptom walkthrough

Astro build fails because a Markdown frontmatter field does not match the Zod schema defined in content.config.ts for the collection. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The Zod schema in content.config.ts enforces a type or required field that the Markdown frontmatter does not satisfy, causing the content loader to reject the entry at build time.

Fix

Update the frontmatter to match the schema, or adjust the schema to accept the existing data shape. If the schema changed, migrate all affected content files before rebuilding. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Run astro check again and confirm zero errors, then run the build and verify the collection entry appears in the generated output. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

npx astro check
head -20 src/content/collection/failing-file.md