From f592ba5eb1fb1a827314b2a93a20078b80e5eaea Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 6 May 2026 10:49:54 -0400
Subject: [PATCH 1/2] fix(nextjs): add runtime error for auth() misimport from
 main entry point

When developers import `auth` from `@clerk/nextjs` instead of
`@clerk/nextjs/server`, the bundler shows a generic "'auth' is not
exported" error with no guidance. Replace the type-only `declare const`
stub with a real runtime Proxy export that throws a clear error message
pointing to the correct import path.

Ref: SDK-65

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../src/__tests__/auth-misimport.test.ts      | 19 +++++++++++++++++++
 packages/nextjs/src/index.ts                  |  2 +-
 packages/nextjs/src/server-only-stubs.ts      | 18 ++++++++++++++++++
 3 files changed, 38 insertions(+), 1 deletion(-)
 create mode 100644 packages/nextjs/src/__tests__/auth-misimport.test.ts
 create mode 100644 packages/nextjs/src/server-only-stubs.ts

diff --git a/packages/nextjs/src/__tests__/auth-misimport.test.ts b/packages/nextjs/src/__tests__/auth-misimport.test.ts
new file mode 100644
index 00000000000..8e9f3813be1
--- /dev/null
+++ b/packages/nextjs/src/__tests__/auth-misimport.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { auth } from '../server-only-stubs';
+
+describe('auth misimport from @clerk/nextjs', () => {
+  it('throws a descriptive error when called as a function', () => {
+    expect(() => (auth as unknown as () => void)()).toThrow("Clerk: auth() was imported from '@clerk/nextjs'");
+    expect(() => (auth as unknown as () => void)()).toThrow("import { auth } from '@clerk/nextjs/server'");
+  });
+
+  it('throws a descriptive error when accessing a property', () => {
+    expect(() => (auth as unknown as Record<string, unknown>).protect).toThrow(
+      "Clerk: auth was imported from '@clerk/nextjs'",
+    );
+    expect(() => (auth as unknown as Record<string, unknown>).protect).toThrow(
+      "import { auth } from '@clerk/nextjs/server'",
+    );
+  });
+});
diff --git a/packages/nextjs/src/index.ts b/packages/nextjs/src/index.ts
index 283a7935cfc..18c5b686352 100644
--- a/packages/nextjs/src/index.ts
+++ b/packages/nextjs/src/index.ts
@@ -96,4 +96,4 @@ export const Show = ComponentsModule.Show as ServerComponentsServerModuleTypes['
  * The `auth` function is only available in server-side contexts:
  * API Routes, Server Components, Server Actions, and Middleware.
  */
-export declare const auth: never;
+export { auth } from './server-only-stubs';
diff --git a/packages/nextjs/src/server-only-stubs.ts b/packages/nextjs/src/server-only-stubs.ts
new file mode 100644
index 00000000000..725e58c9b34
--- /dev/null
+++ b/packages/nextjs/src/server-only-stubs.ts
@@ -0,0 +1,18 @@
+/**
+ * Runtime stubs for server-only exports that are accidentally imported from the
+ * main `@clerk/nextjs` entry point. Each stub is a Proxy that throws a
+ * descriptive error pointing the developer to the correct import path.
+ */
+
+export const auth: never = new Proxy((() => {}) as never, {
+  apply() {
+    throw new Error(
+      `Clerk: auth() was imported from '@clerk/nextjs'. The auth() helper is a server-side function and must be imported from '@clerk/nextjs/server'.\n\nTo fix this, update your import:\n  import { auth } from '@clerk/nextjs/server'`,
+    );
+  },
+  get() {
+    throw new Error(
+      `Clerk: auth was imported from '@clerk/nextjs'. The auth() helper is a server-side function and must be imported from '@clerk/nextjs/server'.\n\nTo fix this, update your import:\n  import { auth } from '@clerk/nextjs/server'`,
+    );
+  },
+});

From 7e031ec07eecb2508496475b21eb0a0a37699b2f Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 6 May 2026 10:54:43 -0400
Subject: [PATCH 2/2] chore: add changeset for auth misimport error

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .changeset/auth-misimport-runtime-error.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/auth-misimport-runtime-error.md

diff --git a/.changeset/auth-misimport-runtime-error.md b/.changeset/auth-misimport-runtime-error.md
new file mode 100644
index 00000000000..26355f119b8
--- /dev/null
+++ b/.changeset/auth-misimport-runtime-error.md
@@ -0,0 +1,5 @@
+---
+"@clerk/nextjs": patch
+---
+
+Improved error message when `auth` is accidentally imported from `@clerk/nextjs` instead of `@clerk/nextjs/server`. Previously, bundlers would show a generic `'auth' is not exported` error. Now, a clear runtime error points developers to the correct import path.