@clerk/nextjs ≥ 7.9.24: module-level displayName mutation breaks App Router PPR resume ("Expected the resume to render <ClerkProvider> … <ReactClerkProvider>")
Maintainers usually reply within 1 day
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 64/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- next.js, react, typescript
- Domain
- backend-api-design
Research direction
Start with dist/esm/pages/ClerkProvider.js and trace how components.client.js and client-boundary/ClerkProvider.js load it alongside the App Router provider. Compare the 7.9.23 and 7.9.24 behavior around ReactClerkProvider.displayName, then run the linked reproduction’s build and request the page twice. Done means both requests resume the prerendered shell without the component-name mismatch or client-render fallback.
Written by the indexing model from the issue text.
Description
Preliminary Checks
-
I have reviewed the documentation: https://clerk.com/docs
-
I have searched for existing issues: https://github.com/clerk/javascript/issues
-
I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)
-
This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.
Reproduction
https://github.com/marcvive/clerk-ppr-resume-repro
Publishable key
pk_test_ZGVsaWNhdGUtYmx1ZWpheS05NDQwLmNsZXJrLmFjY291bnRzLmRldiQ
Description
Since 7.9.24, App Router apps using Partial Prerendering (cacheComponents: true) fail to resume their prerendered shell once a client component importing Show from @clerk/nextjs has been loaded on the server. The route falls back to client rendering on every request after that.
Steps to reproduce:
- Clone the reproduction,
cp .env.local.example .env.localand add the keys of a development instance. npm install && npm run build && npm start- Request the page twice:
curl -s http://localhost:3200/ > /dev/null(twice).
Expected behavior:
Both requests resume the prerendered shell without errors — as they do on @clerk/nextjs 7.9.23 (same repro, npm install @clerk/[email protected] --save-exact, rebuild).
Actual behavior:
The first request is fine. Every later request logs on the server:
Error: Expected the resume to render <ClerkProvider> in this slot but instead it rendered <ReactClerkProvider>. The tree doesn't match so React will fallback to client rendering.
and the browser logs minified React error #419. In our real app this fails our Playwright E2E suite; pinning 7.9.23 fixes it.
Root cause:
In 7.9.24, dist/esm/pages/ClerkProvider.js moved ReactClerkProvider.displayName = "ReactClerkProvider"; from inside the Pages Router ClerkProvider render function to module top level. ReactClerkProvider is InternalClerkProvider from @clerk/react/internal — the same component object the App Router provider (app-router/client/ClerkProvider.js) renders, and which @clerk/react names "ClerkProvider".
components.client.js → client-boundary/ClerkProvider.js imports ../pages/ClerkProvider unconditionally, and Show / ClerkProvider are re-exported from #components (= components.client.js). So the provider's name depends on load order: the build-time prerender records <ClerkProvider> in the postponed state; once a client component using Show is loaded on the server, every resume sees <ReactClerkProvider>. React's resume check compares component names (displayName || name), so it throws.
Hooks such as useAuth alone don't trigger it, because the package is "sideEffects": false and they never load components.client.js.
Suggested fix:
Don't mutate the shared component's displayName: move the assignment back inside the Pages Router render, or wrap the provider in a separately named local component.
Workaround: pin @clerk/[email protected].
Environment
System:
OS: Windows 11 10.0.26200
CPU: (8) x64 Intel(R) Core(TM) Ultra 7 258V
Memory: 10.15 GB / 31.57 GB
Binaries:
Node: 24.22.1 - C:\Program Files\nodejs\node.EXE
npm: 11.19.1 - C:\Program Files\nodejs\npm.CMD
Browsers:
Chrome: 156.0.8078.80
Edge: Chromium (152.0.4191.53)
Firefox: 159.0.1 - C:\Program Files\Mozilla Firefox\firefox.exe
npmPackages:
@clerk/nextjs: 7.9.25 => 7.9.25
next: 16.4.5 => 16.4.5
react: 19.3.1 => 19.3.1
react-dom: 19.3.1 => 19.3.1
- Dominant language
- TypeScript
- Stars
- 1.8k
- Forks
- 492
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 374
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from clerk/javascript
-
<SignIn />: the reset password code step renders an empty, focusable back button with no accessible namePossibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
clerk/javascript#10708 ·
Maintainers usually reply within 1 day
-
Built-in reverification dialog lacks an accessible name (aria-dialog-name)Possibly taken @ItsShivam05 claimed this 5 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
clerk/javascript#10548 ·
Maintainers usually reply within 1 day
-
MFA enrollment QR SVG lacks an accessible name (svg-img-alt)Possibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
clerk/javascript#10547 ·
Maintainers usually reply within 1 day
-
<SignIn />: first "Use email" click switches back to phone when `initialValues.phoneNumber` is setPossibly taken @twicestruck claimed this 22 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
clerk/javascript#10487 ·
Maintainers usually reply within 1 day
-
useLoadedIsomorphicClerk misses "ready" when a ClerkProvider remounts after clerk-js has loaded — <ClerkLoading> never resolvesMay be free again A pull request for this issue was closed without being merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
clerk/javascript#10462 ·
Maintainers usually reply within 1 day
All issues in clerk/javascript
Similar issues
-
`@angular/[email protected]` depends on vulnerable Vite 7.3.7 - GHSA-p4f5-76q4-ffq7 (Critical RCE)Openarea: @angular/build
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
angular/angular-cli#34764 ·
Maintainers usually reply within 1 day
-
status/need-triage
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
google-gemini/gemini-cli#30384 · 1 comment ·
Maintainers usually reply within 1 day
-
P2
Difficulty 1/5 Under an hour Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
bug ready-for-human
Difficulty 2/5 1-3 hours Newbie friendliness 60/100
LucasSantana-Dev/Lucky#3150 ·
Maintainers usually reply within 1 day
-
enhancement good first issue priority: low size: XS
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day