Content collections reference() accepts invalid entry IDs

[smn-cds]

Astro Info

Astro                    v7.0.6
Node                     v24.17.0
System                   macOS (arm64)
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             none

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

No response

Describe the Bug

In Astro v6 and v7, content references are handled inconsistently for entries whose filenames are transformed into different IDs.

Example referenced entry:

src/content/authors/John-Doe.md

Astro's glob loader slugifies the filename and exposes the entry id as:

john-doe

This means getEntry() expects the slugified id:

await getEntry("authors", "john-doe")

However, a reference value using the original filename casing is still accepted during content validation:

{
  "author": "John-Doe"
}

With a schema like:

author: reference("authors")

Astro transforms the reference into:

{
  "author": {
    "id": "John-Doe",
    "collection": "authors"
  }
}

This reference then does not resolve, because the actual entry id is john-doe, not John-Doe.

As a result, invalid references can pass validation and produce broken or silently missing output at build time.

What's the expected result?

Astro should handle referenced entry ids consistently with the entry ids produced by content loading.

Either:

1. Content validation should reject non-slugified references.

For example, this should fail validation if the actual entry id is john-doe:

{
  "author": "John-Doe"
}

Or:

2. Astro should apply the same slugification rules when transforming references.

For example:

{
  "author": "John-Doe"
}

should be transformed into:

{
  "author": {
    "id": "john-doe",
    "collection": "authors"
  }
}

This would make reference() consistent with glob() and getEntry() in Astro v6 and v7.

Link to Minimal Reproducible Example

https://github.com/smn-cds/reproduce-broken-references

Participation

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

[ematipico]

@astrobot-houston triage the issue

[astrobot-houston]

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: Yes — packages/astro/test/units/content-layer/data-transforms.test.ts
• Priority: P4: important. This is a regression from the Zod 4 upgrade (PR Upgrade to Zod 4 #14956) that silently breaks content references. Invalid references pass validation without any error, producing broken output at build time with no clear indication of what went wrong.

This is a regression where reference() validation was accidentally removed during the Zod 4 upgrade. Previously, createReference() in packages/astro/src/content/runtime.ts checked referenced entry IDs against the content store and emitted a Zod validation error for invalid references. After the upgrade, it simply wraps any string into { id, collection } without validation, so references like "John-Doe" are silently accepted even though the glob() loader slugified the actual entry ID to "john-doe".

I found a potential fix for this issue. The fix adds post-sync reference validation to the content layer (packages/astro/src/content/content-layer.ts). After all collections are synced, it walks all entry data to find reference objects and validates that the referenced entries exist in the store, logging an error when an invalid reference is found.

Try this fix

You can test this fix right now without waiting for a release:

npm i https://pkg.pr.new/astro@c0807aa

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Triage Report: Issue #17322

Issue Summary

Title: Content collections reference() accepts invalid entry IDs

Author: smn-cds

Description: When using content collections with the glob() loader, filenames are slugified (e.g., John-Doe.md → id john-doe). However, the reference() schema helper accepts the original un-slugified filename (e.g., John-Doe) during content validation without error. The resulting reference object stores the un-slugified id (John-Doe), which then fails to resolve at runtime because the actual entry id is john-doe.

Environment:

• Astro v7.0.6 (workspace/local build)
• Node.js v22+
• Static output mode
• No adapter

Reproduction Steps

1. Create a content collection authors using glob() loader with a file src/content/authors/John-Doe.md
2. Create a content collection posts using glob() loader with a reference('authors') field in the schema
3. In a post's frontmatter, set author: John-Doe (matching the original filename casing, not the slugified id)
4. Create a page that resolves the reference using getEntry(post.data.author)
5. Run astro build

Expected Result

Either:

• Validation should reject John-Doe as an invalid reference (since the actual entry id is john-doe)
• Or, the reference should be normalized/slugified to match the actual entry id

Actual Result

• Build succeeds with no validation errors — John-Doe is accepted as a valid reference value
• The reference is stored as { id: "John-Doe", collection: "authors" }
• At runtime, resolving the reference fails silently: Entry authors → John-Doe was not found.
• The resolved value is undefined/null, leading to broken output

Build Output (with bug)

generating static routes
  ├─ /index.htmlEntry authors → John-Doe was not found.

Rendered HTML (with bug)

<p>Author ref id: John-Doe</p>
<p>Author resolved: NOT FOUND</p>
<p>Author direct (john-doe): John Doe</p>
<p>Author original (John-Doe): NOT FOUND</p>

Baseline Verification

When using the correctly slugified id john-doe in the post frontmatter, the reference resolves correctly:

<p>Author ref id: john-doe</p>
<p>Author resolved: John Doe</p>

Reproduction Status: ✅ REPRODUCED

Diagnosis

Root Cause

This is a regression introduced during the Zod 4 upgrade (commit 0ff51dfa3c6, PR #14956).

The previous version of createReference() in packages/astro/src/content/runtime.ts validated references against actual entries in the store. The old code checked store.get(collection, lookup) and emitted a Zod validation error if the entry didn't exist. This validation was removed during the Zod 4 upgrade — the new code simply wraps any string into { id: lookup, collection } without checking if the entry exists.

Affected Files

1. packages/astro/src/content/runtime.ts — Line 717: createReference() transform blindly wraps any string into a reference object without validation.
2. packages/astro/src/content/loaders/glob.ts — Lines 41-60: generateIdDefault() slugifies entry IDs using githubSlug().
3. packages/astro/src/content/utils.ts — Lines 357-381: getContentEntryIdAndSlug() uses githubSlug() to lowercase/slugify path segments.

Verdict: bug (confidence: high)

Fix

Added post-sync reference validation to packages/astro/src/content/content-layer.ts. After all content collections are synced (all loaders have completed), a new validation pass walks all entry data looking for reference objects ({ id, collection }) and checks that the referenced entry actually exists in the store. If not, an error is logged.

This approach was chosen over restoring the old inline Zod validation because:

1. During content sync, collections load in parallel (Promise.all), so the referenced collection may not be fully loaded when a reference is being parsed
2. The old code relied on globalDataStore (loaded from disk), which only had data from previous builds
3. Post-sync validation runs after all collections are populated, ensuring reliable validation

Verification

• Build with invalid reference (John-Doe): Error is now logged during content sync
• Build with valid reference (john-doe): No error, reference resolves correctly
• All 66 existing content layer unit tests pass
• 2 new unit tests added and passing
• Content collections integration test passes

Fix status: ✅ FIXED

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.