Astro Content Collectionsの型エラーを直す｜schemaと記事データの照合手順

AstroでMarkdown記事を追加した直後にビルドが止まったら、直す場所は3つのどれかです。記事のfrontmatter(記事の先頭にある設定欄)か、schema(記事データの決まりを書いたファイル)か、その2つの間の食い違いです。

結論を先に言います。エラー文・schema・対象記事の3点をセットで照合してください。 エラー文から「どのコレクション」「どの記事」「どの項目」を拾い、schemaと記事を横に並べて見比べます。schemaをむやみに緩めてはいけません。まず記事を1件だけ直し、同じ検査をもう一度実行します。これが遠回りに見えて一番速い道です。

たとえるなら、schemaは「提出書類のチェックリスト」です。書類(記事)に記入漏れがあるのに、チェックリストの項目を消して通すと、あとで全部の書類が信用できなくなります。だから直すのは、原則として書類の側です。

最初に「構文エラー」か「schema不一致」かを分ける

同じ「ビルドが止まった」でも、エラーは2種類に分かれます。ここを分けないと、直す場所を間違えます。

1つ目は、frontmatterがそもそも読めないエラーです。Astro公式は Failed to parse Markdown frontmatter というエラーとして案内しており、コロンの不足や閉じ引用符の不足がよくある原因だと説明しています。これは中身の値を調べる前の、書き方(構文)の問題です。

2つ目は、読めたけれど中身が決まりに合わないエラーです。こちらはAstro公式の Content entry data does not match schema で、必須フィールドがすべて存在するか、各フィールドが正しい型かを、schemaと照合するよう案内されています。

エラーの種類	起きている場所	代表的な原因	最初に見る場所
frontmatterの解析失敗	記事を読み込む段階	コロンの後の空白不足、閉じ引用符の不足、字下げの乱れ	記事のfrontmatterの書き方
schema不一致	読み込んだ後の検証段階	必須キーの欠落、型違い、候補外の値	schemaと記事の値の対応

書き方のルールの土台はYAMLという形式です。YAML 1.2.2の仕様では、入れ子の構造は字下げで表し、配列の要素は「ハイフン+空白」、キーと値は「コロン+空白」で書くと決まっています。ここが崩れていれば構文エラー、崩れていないのに止まるならschema不一致、と切り分けられます。構文側の直し方はMarkdownのfrontmatterエラーを直す方法で詳しく解説しています。

schemaと対象記事を特定し、上から照合する

次に、見比べる2枚(schemaと記事)の実物を特定します。

1. エラー文を先頭から読み、コレクション名・記事のファイル名・失敗した項目名を一組で控える。
2. schemaの置き場所を開く。Astro公式のContent collectionsガイドでは、ビルド時コレクションは src/content.config.ts(.js や .mjs も可)で定義します。見つからないときは、プロジェクト内で defineCollection を検索してください。
3. その設定の中で、エラーに出たコレクション名と、記事を読み込む範囲(loaderのbaseやpattern)を確認する。別のコレクションのschemaを直してしまう事故を、ここで防ぎます。

このサイトの記事コレクションを例にすると、schemaはおおよそ次の形です。

schema: z.object({
  title: z.string(),
  description: z.string(),
  category: z.enum(['guide', 'trouble']),
  pubDate: z.coerce.date(),
  updatedDate: z.coerce.date().optional(),
  pinned: z.boolean().default(false),
  draft: z.boolean().default(false),
  noteUrl: z.string().optional(),
  tags: z.array(z.string()).default([]),
})

読み方は Zod公式のAPIドキュメントにあります。z.object の中のプロパティは、何も付けなければ全部必須です。.optional() が付いた項目だけ省略でき、.default() が付いた項目は書かなかったときに既定値が入ります。つまり上の例では、title・description・category・pubDate の4つは記事側に必ず必要です。

この決まりを頭に入れて、記事のfrontmatterを上から照合します。症状別の早見表はこうなります。

症状	schema側の書き方	記事側で確認すること	主な修正先
title is required など必須エラー	title: z.string()	キーの欠落、title のつづり、大文字小文字	記事
日付が無効	pubDate: z.coerce.date()	実在する日付か、既存記事と同じ YYYY-MM-DD 形式か	記事
候補外の値	category: z.enum([...])	候補と完全一致か(Trouble や troubles は別の値)	記事、または分類の設計
真偽値の型違い	draft: z.boolean()	true を引用符で囲んで文字列にしていないか	記事
配列の型違い	tags: z.array(z.string())	tags: 'Astro' でなく tags: ['Astro'] になっているか	記事
複数記事で同じ項目が失敗	共通フィールド	schema変更後に直していない記事が残っていないか	全記事を調べてから判断

キー名の照合も忘れないでください。schemaが pubDate なら、pubdate や publishDate は別物として扱われます。また、schemaの作りによっては、決めていないキーを足しただけで弾かれる構成もあります。値を推測で書かず、schemaと、正常にビルドできている既存記事を見本にするのが確実です。

記事側を直すかschema側を直すか判断する

照合して食い違いが見つかったら、どちらを直すかを決めます。判断の軸は1本です。

• 1記事だけの入力漏れ・つづり違い・型違い → 記事側を最小限だけ直す。
• 全記事に効く決まりそのものを変えたい(項目を全記事で省略可にする、新カテゴリを正式に増やす、など) → そのときだけschema側を検討する。

schemaは全記事との契約なので、変更の影響は1記事では済みません。Astro公式ガイドにあるとおり、schemaからはTypeScriptの型も自動生成されます。TypeScriptは型推論によって、存在しないプロパティへのアクセスを検査時に指摘してくれます。裏を返すと、schemaで項目を .optional() に変えれば、その項目は「無いかもしれない値」になり、entry.data.category のような参照箇所すべてで対応が必要になります。

だから、エラーを消すためだけに最初から .optional() や .default() を足すのは避けてください。schemaを変える前に、次の3つを検索して影響範囲を確かめます。

1. 同じキーを持つ全記事(直していない記事が残らないか)。
2. 記事テンプレートなど、entry.data.◯◯ でその項目を参照している場所。
3. 一覧ページ・URL・表示名など、カテゴリ追加なら見た目への影響。

修正後は同じ検査を再実行し、AIへ証拠を渡す

直したら、直る前と同じ条件で検査をやり直します。画面表示の雰囲気ではなく、コマンドの結果で判断してください。

1. 変更した記事のfrontmatterを、正常な既存記事ともう一度見比べる。
2. package.json を開き、プロジェクトで決めている検査コマンド(型検査やビルド)を確認する。
3. そのコマンドを実行する。Astro公式のCLIリファレンスによると、astro dev・astro build・astro check の実行時には astro sync も実行され、astro:content が使う型が生成されます。コマンドの細かい仕様は変わることがあるので、実行時点の公式案内で確認してください。
4. エラーが複数出たら、最初の1件から直し、1件直すたびに同じコマンドを再実行する。
5. 最後の実行結果と終了コード(コマンドの成否を表す数字)を控える。確認方法はWindowsで終了コードを確認する手順にまとめています。

schemaを新規作成・更新した直後に限り、公式ガイドの案内どおり、開発サーバーの再起動やコンテンツ層の同期が必要な場合があります。いきなりキャッシュ削除のような大技に頼らず、保存漏れと構文エラーを除外してから、正規の手順で同期してください。また astro check が通っただけを合格の証明にせず、記事データを実際に読むビルドと組み合わせて確認します。

ここまでの材料は、AIに調査や修正を頼むときの「証拠セット」にもそのまま使えます。次の6点を最初にまとめて渡すと、AIは推測ではなく事実から答えられます。

• エラー文の全文(省略しない)
• 再現コマンド(何を実行したら出たか)
• 終了コード
• 対象記事のfrontmatter全文
• 対象コレクションのschema
• 直前に変更した内容(記事を足した、schemaを変えた、など)

CIでは型検査やビルドが失敗したらデプロイ(公開反映)へ進ませない形にします。全体構成はAstroでMarkdown記事サイトを作る最小構成、配信前ゲートはGitHub Actionsで記事サイトを自動検品する方法で解説しています。

よくある質問

AstroのContent Collectionsのschemaはどこにありますか？

現行の公式ガイドでは、ビルド時コレクションを src/content.config.ts(.js または .mjs も可)で定義します。ただし旧構成や独自構成もあるため、見つからないときはプロジェクト内で defineCollection を検索し、エラーに出たコレクション名と、実際にその記事を読み込んでいる設定を確認してください。

frontmatterの構文エラーとschemaの型エラーはどう見分けますか？

エラー名で見分けます。コロンや閉じ引用符の不足などでfrontmatter自体を解析できなければ構文エラー(Failed to parse Markdown frontmatter)です。解析はできたのに必須項目が無い・型が違うならschema不一致(Content entry data does not match schema)です。最初に出たエラー名と本文を、省略せずに読むのが出発点です。

z.date() と z.coerce.date() は何が違いますか？

Zod公式の説明では、z.date() はDate型そのものを検証し、文字列はそのままでは通りません。z.coerce.date() は入力を日付へ変換してから検証します。Astro公式のfrontmatter例では pubDate に z.coerce.date() が使われています。ただし「coerceなら何でも通る」わけではありません。変換できるかどうかと、その日付が実在して要件どおりかは、分けて確認してください。一律の置き換えもせず、実プロジェクトのschemaを正としてください。

必須項目を .optional() にすれば解決しますか？

その項目を全記事で本当に省略可能にする設計なら、選択肢になります。しかし1記事の入力漏れを隠すためだけにschemaを緩めると、表示側で「値が無い場合」への対応が全部の参照箇所に増えます。まず記事へ正しい値を足せるかを確認し、それと比較してから決めてください。

記事を直したのに同じ型エラーが消えないのはなぜですか？

順番に除外します。①ファイルの保存漏れ、②別の記事で起きている同種のエラー、③別コレクションのschemaを見ていた、の3つがよくある原因です。schemaを新規作成・更新した直後なら、公式ガイドの案内どおり、開発サーバーの再起動またはコンテンツ層の同期が必要な場合もあります。

公式一次情報

確認日: 2026-07-26

• Content collections | Astro Docs: schemaをZodで検証し型を自動生成すること、src/content.config.* での定義、schema更新後の再起動・同期の案内。
• Content entry data does not match schema | Astro Docs: 必須フィールドの存在と各フィールドの型を、schemaと照合して確認するようにという公式の対処。
• Failed to parse Markdown frontmatter | Astro Docs: frontmatter解析失敗の代表例がコロン不足と閉じ引用符不足だという説明。
• CLI Commands | Astro Docs: astro dev・astro build・astro check が astro sync も実行し、astro:content の型を生成すること。
• Defining schemas | Zod: objectのプロパティは既定で必須、.optional() はundefinedを許可、.default() は未入力時に既定値を返すこと、enum・array・dateの定義。
• YAML 1.2.2 仕様: 字下げによる構造、配列は「ハイフン+空白」、キーと値は「コロン+空白」という記法と、真偽値の正準形。

まとめ

型エラーはschemaと記事データの差です。次の3つをこの順で実行してください。

• エラー名で「構文エラー」か「schema不一致」かを分け、エラー文からコレクション名・記事・項目を一組で控える。
• src/content.config.* のschemaと記事のfrontmatterを横に並べ、必須項目・型・値の順に照合して、まず記事側を1件だけ最小修正する。
• 直したら同じコマンドで再検査し、終了コードまで残す。schemaを変えるのは、全記事・テンプレート・生成型への影響を調べてからにする。