`@clerk/nextjs` with `cacheComponents`: after a root param change (`/en` → `/sk`), `Clerk.navigate()` within `/sk` never resolves

Abierto
#10,539 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

@Joozty ya está trabajando en esto.

Desde el 30/10/2026.

  • #10540 de @Joozty — abierto

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
next.js, react, typescript

Línea de trabajo

Start with packages/nextjs/src/app-router/client/useInternalNavFun.ts and compare when its navigation function is saved during render with the proposed layout-effect approach. Reproduce the hang using the linked repro and its /en to /sk steps; check the existing cacheComponents sign-out tests mentioned in #7996. Done means Clerk.navigate() resolves after a language switch and the linked sign-in/sign-out cases no longer hang.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

needs-triage
Preliminary Checks
Reproduction

https://github.com/Joozty/clerk-nextjs-activity-repro

Publishable key

Not shared. The reproduction works with any development instance: put your own key in .env.local (see .env.example).

Description

With cacheComponents: true, a client-side navigation that changes a root param keeps the old root layout tree mounted, but hidden in <Activity>. For example, this happens when you click a link from /en to /sk with app/[lang]/layout.jsx. After that, a Clerk.navigate() call that stays in /sk never resolves. setActive() and signOut() wait for navigate(), so sign-in and sign-out can get stuck.

Steps to reproduce:

  1. Clone the reproduction and run pnpm install.
  2. Copy .env.example to .env.local. Set the publishable key of your own development instance there.
  3. Run pnpm dev and open http://localhost:3000/en.
  4. Click Test Clerk.navigate(). It shows resolved.
  5. Click the /sk link. Then click Test Clerk.navigate() again.

Expected behavior:

resolved, like in step 4.

Actual behavior:

still pending after 3 seconds. The promise never resolves. The button navigates to the current page, so the URL doesn't change.

  • pnpm build and pnpm start give the same result.
  • partialPrefetching: false gives the same result.
  • Without cacheComponents, the promise resolves. (Remove both cacheComponents and partialPrefetching from next.config.mjs.)
  • On /sk, await Clerk.navigate('/en') resolves, because it goes to the other language. It also resolves the promise that was stuck.

Why it happens:

  1. In the browser, Next.js puts the value of [lang] in the React key of the segment. So /en and /sk are two different React trees. With cacheComponents, Next.js doesn't unmount the /en tree. It hides the tree in <Activity>. Now two ClerkProviders are mounted.
  2. useInternalNavFun (packages/nextjs/src/app-router/client/useInternalNavFun.ts) saves its navigation function in window.__clerk_internal_navigations[name].fun during render.
  3. The hidden tree still renders. useRouter() from next/navigation reads LayoutRouterContext, and Next.js gives this context a new value on every navigation. So after each navigation, the hidden ClerkProvider renders after the visible one. Its function replaces the visible tree's function.
  4. The hidden tree's function starts the navigation with the hidden tree's startTransition. The promise resolves only when an effect runs: the isPending effect of the hidden tree, or the effect that runs when a ClerkProvider is shown or hidden. React doesn't run effects in a hidden tree. So the promise resolves only when a navigation shows or hides a tree, for example /sk → /en.
  5. Later calls with the same URL don't navigate at all, because pendingDestination is still that URL.

What users see:

I tested this with a real account:

  • Open /en, click /sk, and sign in with email in the modal. The sign-in gets stuck. Clerk creates the session, but the page shows no user button and no Sign in button until you reload. The modal goes back to the current page, so setActive() waits for a navigation in the same language.
  • Open /en, click /sk, click /en, and sign out. The sign-out gets stuck in the same way, because afterSignOutUrl (/en) is in the current language.
  • Open /en, click /sk, and sign out. This sign-out finishes, but only because of a second bug (#10538): clerk-js keeps the first afterSignOutUrl, so the sign-out goes to the other language, /en.
  • Sign-in with Google is not affected, because it comes back with a full page load.
  • With the fix below, both stuck cases finish.

Possible fix:

Save fun in a layout effect instead of during render. React doesn't run layout effects in a hidden tree. When the tree becomes visible, React runs its layout effects again. So fun always belongs to the visible tree:

// useInternalNavFun.ts
import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';

// Use this instead of the `if (windowNav) { … }` block:
useSafeLayoutEffect(() => {
  if (windowNav) {
    getClerkNavigationObject(name).fun = (to, opts) => {
      // unchanged
    };
  }
});

The reproduction has this change as a pnpm patch. With the patch, Clerk.navigate() resolves after every language switch. The README explains how to apply the patch.

Related:

  • #10538 is the second bug in the same reproduction: afterSignOutUrl keeps its first value.
  • #2899 and #3480 moved this navigation function to window and set it during render. This design expects only one mounted ClerkProvider.
  • #7989 removed usePathname from this hook for cacheComponents. Since then, only isPending or a ClerkProvider that mounts or unmounts resolves the waiting promises.
  • #7865 fixed another promise in this hook that never resolved, but the trigger was different: a second push to the same URL.
  • #7996 added cacheComponents sign-out tests, and #8071 skipped them because toBeSignedOut() timed out. They are still skipped on main. That test app has one root layout without params, so the cause may be different.
  • #9987 also makes setActive() and signOut() hang, but the cause is different: there, onBeforeSetActive never finishes. Its fix, #10088, doesn't change useInternalNavFun, so it won't fix this bug.
  • #9405 had a similar hang after sign-in, but #9406 traced it to a Next.js router bug that Next 16.3.0 fixed.
  • vercel/next.js#86577 is the Next.js issue about cacheComponents keeping earlier routes, even the previous language, mounted in a hidden <Activity>.
  • pacocoursey/next-themes#375 is the same kind of bug in next-themes: after a language switch, the hidden ThemeProvider of the old language writes a stale theme.
Environment
System:
    OS: macOS 27.2
    CPU: (10) arm64 Apple M4
    Memory: 73.23 MB / 32.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 24.15.0 - /Users/jozef/.volta/tools/image/node/24.15.0/bin/node
    npm: 11.12.1 - /Users/jozef/.volta/tools/image/node/24.15.0/bin/npm
    pnpm: 12.4.1 - /Users/jozef/.volta/bin/pnpm
  Browsers:
    Chrome: 156.0.8078.48
    Firefox: 159.0
    Safari: 27.2
  npmPackages:
    @clerk/nextjs: 7.9.22 => 7.9.22
    next: 16.4.3 => 16.4.3
    react: 19.3.0 => 19.3.0
    react-dom: 19.3.0 => 19.3.0
  Loaded from the Frontend API:
    @clerk/clerk-js: 6.41.0 (6.42.0 and main have the same code)
    @clerk/ui: 1.42.0
Lenguaje dominante
TypeScript
Estrellas
1.8k
Forks
492
Merge medio
1 d 7 h
PR fusionados (30 d)
357

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de clerk/javascript

Todos los issues de clerk/javascript

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.