docs: clarify /_not-found failures and <html> attribute reads under Cache Components#95163
Merged
aurorascharff merged 10 commits intoJun 25, 2026
Merged
Conversation
Contributor
Stats skippedCommit: defc3e2 |
Contributor
Tests PassedCommit: defc3e2 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves Cache Components documentation by clarifying two common sources of confusion: why validation failures can surface on the synthetic /_not-found route, and why reading request-bound values to set <html> attributes can’t be “fixed” with <Suspense> in a child component.
Changes:
- Update the “blocking prerender” error docs to explain why
/_not-foundcan be the reported failing route and how to trace the real source (root layout). - Expand the troubleshooting guidance about differences between
next devoverlays vs abbreviatednext buildstacks, and point to--debug-prerender/--debug-build-paths. - Add guidance and an example for avoiding theme flash when the theme is stored in cookies, without making the root layout request-bound.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| errors/blocking-prerender-runtime.mdx | Adds /_not-found gotcha and refines guidance on debugging blocking routes under Cache Components. |
| errors/blocking-prerender-dynamic.mdx | Mirrors the debugging guidance and adds the /_not-found clarification for uncached-data failures. |
| docs/01-app/02-guides/preventing-flash-before-hydration.mdx | Adds a cookie-based theme pattern using a pre-paint inline script to keep the shell static. |
| docs/01-app/02-guides/migrating-to-cache-components.mdx | Adds a “Good to know” callout explaining <html> attribute constraints and links to the recommended pattern. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
icyJoseph
approved these changes
Jun 25, 2026
aurorascharff
deleted the
aurorascharff/docs-not-found-html-attribute-gotcha
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When the root layout reads request data (
cookies(),headers()) under Cache Components, the validation error often surfaces on/_not-found— a real prerendered route that inherits the root layout, even though the user has nonot-found.tsxfile. This is consistently confusing (#67532), so:errors/blocking-prerender-runtime.mdxanderrors/blocking-prerender-dynamic.mdx: added a gotcha bullet pointing the fix at the root layout when the failing route is/_not-found.docs/01-app/02-guides/migrating-to-cache-components.mdx: added aGood to knowcallout in thecookies, headers, and searchParamssection linking to the existing Themes recipe for the<html data-theme>case, since attributes on the root element can not be wrapped in<Suspense>.Verification
npx alexclean on all three files.