diff --git a/.changeset/nextjs-cache-components-support.md b/.changeset/nextjs-cache-components-support.md
new file mode 100644
index 00000000000..b8938cffea7
--- /dev/null
+++ b/.changeset/nextjs-cache-components-support.md
@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for Next.js 16 cache components by improving error detection and providing helpful error messages when `auth()` or `currentUser()` are called inside a `"use cache"` function.
diff --git a/integration/templates/next-cache-components/src/app/api/use-cache-error-trigger/route.ts b/integration/templates/next-cache-components/src/app/api/use-cache-error-trigger/route.ts
new file mode 100644
index 00000000000..e4e7cb95f03
--- /dev/null
+++ b/integration/templates/next-cache-components/src/app/api/use-cache-error-trigger/route.ts
@@ -0,0 +1,19 @@
+import { auth } from '@clerk/nextjs/server';
+
+// This function deliberately calls auth() inside "use cache" to trigger the error
+async function getCachedAuthData() {
+ 'use cache';
+ // This WILL throw an error because auth() uses headers() internally
+ const { userId } = await auth();
+ return { userId };
+}
+
+export async function GET() {
+ try {
+ const data = await getCachedAuthData();
+ return Response.json(data);
+ } catch (e: any) {
+ // Return the error message so we can verify it in tests
+ return Response.json({ error: e.message }, { status: 500 });
+ }
+}
diff --git a/integration/templates/next-cache-components/src/app/current-user-cache-correct/page.tsx b/integration/templates/next-cache-components/src/app/current-user-cache-correct/page.tsx
new file mode 100644
index 00000000000..a7e4f82f11a
--- /dev/null
+++ b/integration/templates/next-cache-components/src/app/current-user-cache-correct/page.tsx
@@ -0,0 +1,93 @@
+import { Suspense } from 'react';
+import { currentUser, clerkClient } from '@clerk/nextjs/server';
+
+// Simulated cached operation that fetches additional user data
+async function getCachedUserProfile(userId: string) {
+ 'use cache';
+ // This is the CORRECT pattern:
+ // - currentUser() is called OUTSIDE the cache function
+ // - Only the userId is passed into the cache function
+ // - The cache function uses clerkClient() which is allowed in cache contexts
+ const client = await clerkClient();
+ const user = await client.users.getUser(userId);
+
+ return {
+ userId,
+ cachedAt: new Date().toISOString(),
+ profile: {
+ fullName: [user.firstName, user.lastName].filter(Boolean).join(' ') || 'Unknown',
+ emailCount: user.emailAddresses?.length ?? 0,
+ },
+ };
+}
+
+async function CurrentUserCacheContent() {
+ // Step 1: Call currentUser() OUTSIDE the cache function
+ const user = await currentUser();
+
+ if (!user) {
+ return (
+ <>
+ Please sign in to test the caching pattern with currentUser().
+ Not signed in
+
+ );
+ }
+
+ // Step 2: Pass userId INTO the cache function
+ const cachedProfile = await getCachedUserProfile(user.id);
+
+ return (
+ <>
+
+ This demonstrates the correct way to use "use cache" with currentUser():
+
+
+ -
+ Call
currentUser() outside the cache function
+
+ -
+ Pass the
userId into the cache function
+
+ -
+ Use
clerkClient() inside the cache function (allowed)
+
+
+
+
+
Cached Profile Data:
+
{JSON.stringify(cachedProfile, null, 2)}
+
{user.id}
+
+
+ {`
+// Correct pattern:
+const user = await currentUser(); // Outside cache
+if (user) {
+ const profile = await getCachedProfile(user.id); // Pass userId in
+}
+
+async function getCachedProfile(userId: string) {
+ 'use cache';
+ const client = await clerkClient();
+ return client.users.getUser(userId);
+}
+ `}
+
+
+ );
+}
+
+export default function CurrentUserCacheCorrectPage() {
+ return (
+
+ currentUser() with "use cache" Correct Pattern
+
+ Loading...}>
+
+
+
+ );
+}
diff --git a/integration/templates/next-cache-components/src/app/current-user-server-component/page.tsx b/integration/templates/next-cache-components/src/app/current-user-server-component/page.tsx
new file mode 100644
index 00000000000..54682ee1d74
--- /dev/null
+++ b/integration/templates/next-cache-components/src/app/current-user-server-component/page.tsx
@@ -0,0 +1,43 @@
+import { Suspense } from 'react';
+import { currentUser } from '@clerk/nextjs/server';
+
+async function CurrentUserContent() {
+ const user = await currentUser();
+
+ return (
+ <>
+
+
Current User Result:
+
+ {JSON.stringify(
+ {
+ id: user?.id ?? null,
+ firstName: user?.firstName ?? null,
+ lastName: user?.lastName ?? null,
+ primaryEmailAddress: user?.primaryEmailAddress?.emailAddress ?? null,
+ isSignedIn: !!user,
+ },
+ null,
+ 2,
+ )}
+
+
{user?.id ?? 'Not signed in'}
+ {user?.primaryEmailAddress?.emailAddress ?? 'No email'}
+
+ );
+}
+
+export default function CurrentUserServerComponentPage() {
+ return (
+
+ currentUser() in Server Component
+ This page tests using currentUser() in a standard React Server Component.
+
+ Loading user...}>
+
+
+
+ );
+}
diff --git a/integration/templates/next-cache-components/src/app/page.tsx b/integration/templates/next-cache-components/src/app/page.tsx
index d76a0666b61..5d863924bba 100644
--- a/integration/templates/next-cache-components/src/app/page.tsx
+++ b/integration/templates/next-cache-components/src/app/page.tsx
@@ -12,6 +12,9 @@ export default function Home() {
auth() in Server Component
+
+ currentUser() in Server Component
+
auth() in Server Action
@@ -19,10 +22,16 @@ export default function Home() {
auth() in API Route
- use cache with auth() (should error)
+ use cache with auth() (documentation)
+
+
+ use cache error trigger (actual error)
+
+
+ "use cache" correct pattern (auth)
- "use cache" correct pattern
+ "use cache" correct pattern (currentUser)
PPR with auth()
diff --git a/integration/templates/next-cache-components/src/app/use-cache-error-trigger/page.tsx b/integration/templates/next-cache-components/src/app/use-cache-error-trigger/page.tsx
new file mode 100644
index 00000000000..2acba59609f
--- /dev/null
+++ b/integration/templates/next-cache-components/src/app/use-cache-error-trigger/page.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export default function UseCacheErrorTriggerPage() {
+ const [error, setError] = useState(null);
+ const [loading, setLoading] = useState(false);
+
+ const triggerError = async () => {
+ setLoading(true);
+ setError(null);
+ try {
+ const response = await fetch('/api/use-cache-error-trigger');
+ const data = await response.json();
+ if (data.error) {
+ setError(data.error);
+ }
+ } catch (e: any) {
+ setError(e.message);
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ useEffect(() => {
+ triggerError();
+ }, []);
+
+ return (
+
+ "use cache" Error Trigger
+ This page triggers an actual error by calling auth() inside a "use cache" function.
+
+ {loading && Loading...
}
+
+ {error && (
+
+
Error Caught:
+
{error}
+