Content collection validation errors in v6 are no longer human-readable

[smn-cds]

Astro Info

Astro                    v6.0.5
Node                     v24.13.0
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

Astro v6 appears to have regressed the formatting of content collection validation errors.

When a content entry fails schema validation, the error output now includes what looks like a raw serialized zod error instead of a human-readable message. In practice, this makes the important information harder to spot and makes the output feel accidental rather than intentional.

For example, I have a collection entry missing a required label property. Running astro dev produces:

[InvalidContentEntryDataError] test-collection → test-entry data does not match collection schema.

  **: [
  {
    "expected": "object",
    "code": "invalid_type",
    "path": [
      "label"
    ],
    "message": "label: Required"
  }
]

  Hint:
    See https://docs.astro.build/en/guides/content-collections/ for more information on content schemas.
  Error reference:
    https://docs.astro.build/en/reference/errors/invalid-content-entry-data-error/

The **: line in particular looks unintended, and the validation details are shown as a raw zod error dump instead of a concise user-facing message.

What's the expected result?

The same validation failure should be presented in a clearer, human-readable format - restoring Astro v5's behaviour.

Link to Minimal Reproducible Example

I can provide a repro repo if needed, but the issue is straightforward to reproduce:

• Create a content collection.
• Add a invalid JSON entry.
• Run astro dev.

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

I was able to reproduce this issue. The root cause is a regression introduced during the Zod v3 → v4 migration (PR #14956, commit 0ff51dfa3c). In Zod v4, $ZodError.message returns a raw JSON-stringified array of issues instead of a human-readable string, but the error formatting code in errors-data.ts was updated to use error.message directly instead of iterating over individual issues. This produces the **: [{ "expected": ... }] dump instead of the clean **label**: Required output that Astro v5 provided.

I was able to fix this issue. The fix replaces error.message with ...error.issues.map((issue) => ...) in three affected error definitions (InvalidContentEntryFrontmatterError, InvalidContentEntryDataError, and ContentEntryDataError), matching the correct pattern already used in formatZodError from content/loaders/errors.ts. All content layer and content collection tests pass after the fix. View Suggested Fix

Priority P4: important. This violates the documented behavior shown in the JSDoc for InvalidContentEntryDataError and affects all users of content collections who encounter schema validation errors in Astro v6. While it doesn't break functionality, it makes error messages effectively unreadable, significantly degrading the developer experience for anyone debugging content schema issues.

Full Triage Report

Issue #15976: Content collection validation errors in v6 are no longer human-readable

Verification

Reporter's Claim

• Current behavior: Content collection validation errors display raw serialized JSON from Zod v4's $ZodError.message property, including **: [{ "expected": "object", "code": "invalid_type", ... }] output. The **: prefix shows an empty path and the body is a JSON dump of the issues array.
• Expected behavior: Validation errors should be formatted in a clear, human-readable format (e.g., **label**: Required), restoring Astro v5's behavior where each issue was listed individually with its path and message.

Verdict: bug

Confidence: high

Evidence

1. Regression introduced in Zod v4 upgrade (PR #14956, commit 0ff51dfa3c)

The change at packages/astro/src/core/errors/errors-data.ts:1744 replaced the Zod v3 error formatting with a broken Zod v4 equivalent:

Before (Zod v3, working correctly):

...error.errors.map((zodError) => `  **${zodError.path.join('.')}**: ${zodError.message}`)

This iterated over each individual Zod error, formatting them as **fieldName**: error message.

After (Zod v4, broken):

`  **: ${error.message}`

In Zod v4, $ZodError.message returns the raw JSON-stringified issues array, not a human-readable concatenation of messages. This produces the output the reporter observed.

2. The **: prefix is an artifact of incomplete migration

The old code included the path from each individual error: **${zodError.path.join('.')}**. The new code has a hardcoded empty path **, resulting in **: [json dump].

3. Correct Zod v4 pattern exists elsewhere in the codebase

• packages/astro/src/content/loaders/errors.ts:3-4 — formatZodError correctly iterates error.issues and formats each as **${issue.path.join('.')}**: ${issue.message}.
• packages/astro/src/core/messages/runtime.ts:233-246 — formatConfigErrorMessage correctly iterates err.issues.

Both demonstrate the correct Zod v4 approach was known and used in other parts of the codebase during the same upgrade.

4. Documentation explicitly shows human-readable formatting

The JSDoc for InvalidContentEntryDataError (lines 1728-1731) shows the expected output:

**blog** → **post** data does not match collection schema.
"title" is required.
"date" must be a valid date.

The raw JSON output contradicts the documented intent.

5. Confirmed via runtime test

Running Zod v4 in the repo confirms $ZodError.message returns raw JSON:

error.message: [
  {
    "expected": "string",
    "code": "invalid_type",
    "path": ["label"],
    "message": "Invalid input: expected string, received undefined"
  }
]

6. Two error definitions affected

Both InvalidContentEntryDataError (line 1738) and ContentEntryDataError (line 1844) have the same broken formatting pattern. Both were changed in the same commit.

Root Cause

During the Zod v3 → v4 upgrade in PR #14956, the InvalidContentEntryDataError and ContentEntryDataError message functions were updated to use error.message (Zod v4's $ZodError.message), which returns a JSON string of all issues. The old code used error.errors (Zod v3's array of error objects) and mapped over them individually to produce formatted strings. The migration did not account for the different semantics of .message between Zod v3 and v4.

Fix Applied

Replaced error.message with proper iteration over error.issues in three error definitions:

1. InvalidContentEntryFrontmatterError (line 1714): Replaced error.message with ...error.issues.map(...).
2. InvalidContentEntryDataError (line 1742): Replaced ` **: ${error.message}` with ...error.issues.map(...).
3. ContentEntryDataError (line 1848): Same fix.

Before fix:

[InvalidContentEntryDataError] test-collection → test-entry data does not match collection schema.

  **: [
  {
    "expected": "object",
    "code": "invalid_type",
    "path": ["label"],
    "message": "label: Required"
  }
]

After fix:

[InvalidContentEntryDataError] test-collection → test-entry data does not match collection schema.

  **label**: Required

All content layer and content collection tests pass after the fix (62 + 25 tests).

This report was made by an LLM. Mistakes happen, check important info.

[shanliuling]

I've submitted a Pull Request to fix this issue #15982