errors: centralize and DX-friendly "use cache" error messages#94300
Open
aurorascharff wants to merge 6 commits into
Open
errors: centralize and DX-friendly "use cache" error messages#94300aurorascharff wants to merge 6 commits into
aurorascharff wants to merge 6 commits into
Conversation
Contributor
Stats cancelledCommit: cc598e5 |
Contributor
Failing test suitesCommit: cc598e5 | About building and testing Next.js
Expand output● use-cache-search-params › when searchParams are used inside of "use cache" › should show an error ● use-cache-search-params › when searchParams are caught inside of "use cache" › should show an error ● use-cache-search-params › when searchParams are caught inside of "use cache" › should also show an error after the second reload ● use-cache-search-params › should show an error when searchParams are used inside of a cached generateMetadata ● use-cache-search-params › should show an error when searchParams are used inside of a cached generateViewport
Expand output● dynamic-data inside cache scope › displays redbox when accessing dynamic data inside a cache scope
Expand output● dynamic-data inside cache scope › displays redbox when accessing dynamic data inside a cache scope
Expand output● instant-navigation-testing-api › renders runtime-prefetched content instantly during navigation ● instant-navigation-testing-api › runtime params are excluded from instant shell › does not include cookie values in instant shell during page load
Expand output● use-cache-search-params › when searchParams are used inside of "use cache" › should show an error ● use-cache-search-params › when searchParams are caught inside of "use cache" › should show an error ● use-cache-search-params › when searchParams are caught inside of "use cache" › should also show an error after the second reload ● use-cache-search-params › should show an error when searchParams are used inside of a cached generateMetadata ● use-cache-search-params › should show an error when searchParams are used inside of a cached generateViewport
Expand output● app-dir - server-action-period-hash-custom-key › should have a different manifest if the encryption key from process env is changed ● app-dir - server-action-period-hash-custom-key › should have the same manifest if the encryption key from process env is same
Expand output● app-dir - server-action-period-hash › should have same manifest between continuous two builds ● app-dir - server-action-period-hash › should have different manifest between two builds with period hash
Expand output● dynamic-data inside cache scope › displays redbox when accessing dynamic data inside a cache scope Other failing CI jobs |
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull request overview
This PR centralizes and rewrites "use cache" / "use cache: private" misuse errors into a single message factory module, aiming to provide shorter, action-oriented diagnostics with consistent “Learn more” links across the server runtime and dev overlay.
Changes:
- Added
use-cache-messages.tsto centralize"use cache"-related error factories/strings and updated server call sites to use it. - Updated e2e expectations and regenerated
packages/next/errors.jsonentries for the new/rewritten messages. - Tweaked dev overlay styling to improve spacing for chained
Caused by:error blocks.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/e2e/app-dir/cache-components-errors/cache-components-errors.test.ts | Updates expected error codes/messages for "use cache" scenarios. |
| packages/next/src/server/web/spec-extension/revalidate.ts | Switches to centralized revalidate-in-cache error factories. |
| packages/next/src/server/use-cache/use-cache-wrapper.ts | Uses centralized "use cache" message exports for private/nested cache errors. |
| packages/next/src/server/use-cache/use-cache-messages.ts | New module providing centralized "use cache" error factories, messages, and doc URLs. |
| packages/next/src/server/use-cache/cache-tag.ts | Uses centralized error factory for cacheTag() outside "use cache". |
| packages/next/src/server/use-cache/cache-life.ts | Uses centralized error factory for cacheLife() outside "use cache". |
| packages/next/src/server/route-modules/app-route/module.ts | Uses centralized request-in-cache error factories for App Route handlers. |
| packages/next/src/server/request/utils.ts | Uses centralized searchParams-in-cache error factory. |
| packages/next/src/server/request/headers.ts | Uses centralized headers() misuse error factories for cache/unstable_cache. |
| packages/next/src/server/request/draft-mode.ts | Uses centralized draft-mode mutation-in-cache error factories. |
| packages/next/src/server/request/cookies.ts | Uses centralized cookies() misuse error factories for cache/unstable_cache. |
| packages/next/src/server/request/connection.ts | Uses centralized connection() misuse error factories for cache/private/unstable_cache. |
| packages/next/src/next-devtools/dev-overlay/container/runtime-error/error-cause.tsx | Adjusts .error-cause-message margin for better overlay spacing. |
| packages/next/errors.json | Adds/updates error-code mappings for the new centralized messages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Additional Suggestion:
use-cache-search-params.test.ts asserts the old searchParams-in-use-cache error message and error code (E842), which no longer match the rewritten message produced by createSearchParamsInUseCacheError (E1289), causing the test to fail in CI.
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.
What?
Centralizes all
"use cache"error messages into one factory module and rewrites them as short, DX-friendly prose with aLearn more:link. Adds the learn-more URLs that several factories were missing.Why?
Old wording was paragraph-style and scattered across 9 files. New wording is one short imperative sentence + link, so developers (and agents) get the fix immediately.
How?
packages/next/src/server/use-cache/use-cache-messages.tswith 15 factories, 2 const strings, and 7 docs URLs. All 9 call sites import from here.Route "${route}": [api] can't be [verb] inside \"use cache"`. [one-line fix].\nLearn more: ${URL}`..error-cause-messagebottom margin so chainedCaused by:blocks match the outer error's spacing before the code frame.errors.json(E1287–E1305).Verification
Test-app scenarios on the error-messages-overhaul demo: 66-cookies, 67-headers, 68-searchParams, 69-connection, 70-draftMode, 72-nested-zero-revalidate, 73-nested-short-expire, 74-private-in-public, 75-private-in-gsp, 76-cacheTag-outside, 77-cacheLife-outside.