feat(nextjs): Fix error when using PPR with auth() #7530

jacekradko · 2025-12-27T22:16:25Z

Description

In an app that has PPRenabled when using await auth() in an API route we see the following pre-rendering error during build:

web:build: ✓ Compiled successfully in 14.8s
web:build:   Skipping validation of types
web:build: ✓ Collecting page data using 11 workers in 1514.3ms 
Error fetching task events: Error: Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).
web:build: If you're using /pages, try getAuth() instead.
web:build: Original error: Error: During prerendering, `headers()` rejects when the prerender is complete. Typically these errors are handled by React but if you move `headers()` to a different context by using `setTimeout`, `after`, or similar functions you may observe this error and you should handle it in that context. This occurred at route "/api/tasks/events".
web:build:     at async n (src/lib/api-permissions.ts:21:29)
web:build:     at async w (src/app/api/tasks/events/route.ts:13:24)
web:build:   19 |   orgId: string | null | undefined;
web:build:   20 | }> {
web:build: > 21 |   const { userId, orgId } = await auth();
web:build:      |                             ^
web:build:   22 |
web:build:   23 |   if (!userId) {
web:build:   24 |     throw NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
web:build: ✓ Generating static pages using 11 workers (95/95) in 572.0ms
web:build: ✓ Finalizing page optimization in 885.1ms 
web:build: 
web:build: Route (app)
web:build: ┌ ◐ /
web:build: ├ ◐ /_not-found
web:build: ├ ƒ /.well-known/oauth-authorization-server
web:build: ├ ƒ /.well-known/oauth-protected-resource/mcp
web:build: ├ ƒ /api/tasks
web:build: ├ ƒ /api/tasks/events
web:build: ├ ◐ /settings
web:build: 
web:build: 
web:build: ƒ Proxy (Middleware)
web:build: 
web:build: ○  (Static)             prerendered as static content
web:build: ◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
web:build: ƒ  (Dynamic)            server-rendered on demand
web:build:

Adding await connection() to auth() to signal to next.js that the route is not eligible for PPR.

Related: USER-4044

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Bug Fixes
- Prevents prerendering failures when using auth() with Next.js Cache Components and surfaces clearer errors for incompatible cache/use-cache scenarios, including a runtime guard for Next.js 16.
Tests
- Added unit tests covering prerendering bailout and cache-related error detection.
Chores
- Added a changeset entry documenting a patch release.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

changeset-bot · 2025-12-27T22:16:29Z

🦋 Changeset detected

Latest commit: 564e8a0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-12-27T22:16:29Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Skipped		Jan 7, 2026 2:56am

coderabbitai · 2025-12-27T22:18:08Z

📝 Walkthrough

Walkthrough

A runtime guard was added to auth() to dynamically import and invoke Next.js 16's connection() to opt out of prerendering when available, with prerender bailout errors rethrown. A new isNextjsUseCacheError helper (precompiled regexes) was introduced and integrated into request-building and error handling to detect and propagate Next.js "use cache" errors. Prerendering bailout detection was extended to cover headers() rejections. Unit tests for the error predicates were added and a patch changeset was created.

Pre-merge checks

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.
Title check	❓ Inconclusive	The title refers to PPR (Partial Pre-Rendering) and auth(), but the primary change focuses on Next.js 16 cache components support, not PPR specifically.	Consider clarifying the title to reflect the core objective: supporting Next.js cache components with auth(), as PPR is one aspect of this broader support.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR implements baseline Next.js cache components support by adding connection() call and error handling for use-cache scenarios, directly meeting USER-4044 requirements.
Out of Scope Changes check	✅ Passed	All changes are focused on supporting cache components and preventing errors with auth(): connection() guard, use-cache error detection, and appropriate error handling.

📜 Recent review details

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between e11aed5 and 564e8a0.

📒 Files selected for processing (2)

packages/nextjs/src/app-router/server/__tests__/utils.test.ts
packages/nextjs/src/app-router/server/utils.ts

🚧 Files skipped from review as they are similar to previous changes (1)

packages/nextjs/src/app-router/server/tests/utils.test.ts

🧰 Additional context used

📓 Path-based instructions (10)

**/*.{js,jsx,ts,tsx}