From f63c2dbea14da56b65a6e81000b0fda6ca8880fe Mon Sep 17 00:00:00 2001 From: Jacek Date: Fri, 6 Mar 2026 10:56:30 -0600 Subject: [PATCH 1/3] fix(nextjs): improve auth() error message to mention infrastructure failures --- .changeset/improve-auth-middleware-error-message.md | 5 +++++ packages/nextjs/src/server/errors.ts | 1 + 2 files changed, 6 insertions(+) create mode 100644 .changeset/improve-auth-middleware-error-message.md diff --git a/.changeset/improve-auth-middleware-error-message.md b/.changeset/improve-auth-middleware-error-message.md new file mode 100644 index 00000000000..2f71f2a258d --- /dev/null +++ b/.changeset/improve-auth-middleware-error-message.md @@ -0,0 +1,5 @@ +--- +"@clerk/nextjs": patch +--- + +Improved `auth()` error message when `clerkMiddleware()` is not detected to mention that infrastructure issues (e.g. edge runtime errors or platform outages) can also cause this error. diff --git a/packages/nextjs/src/server/errors.ts b/packages/nextjs/src/server/errors.ts index 59f13223656..b41582c83c7 100644 --- a/packages/nextjs/src/server/errors.ts +++ b/packages/nextjs/src/server/errors.ts @@ -27,6 +27,7 @@ export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[ - ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js ${fileReference} file. - Your ${fileReference} matcher is configured to match this route or page. - If you are using the src directory, make sure the ${fileReference} file is inside of it. +- If your ${fileReference} file and matcher are configured correctly, this error can also occur if the ${fileReference} failed to run on this request (e.g. due to an edge runtime error or platform outage). For more details, see https://clerk.com/err/auth-middleware `; From d16df7dc005d3e22fa0fc31281ab7f8279bd6fa6 Mon Sep 17 00:00:00 2001 From: Jacek Date: Mon, 9 Mar 2026 10:40:58 -0500 Subject: [PATCH 2/3] fix(nextjs): separate infrastructure failure note from checklist in auth error message --- packages/nextjs/src/server/errors.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/nextjs/src/server/errors.ts b/packages/nextjs/src/server/errors.ts index b41582c83c7..59bfa998543 100644 --- a/packages/nextjs/src/server/errors.ts +++ b/packages/nextjs/src/server/errors.ts @@ -27,7 +27,8 @@ export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[ - ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js ${fileReference} file. - Your ${fileReference} matcher is configured to match this route or page. - If you are using the src directory, make sure the ${fileReference} file is inside of it. -- If your ${fileReference} file and matcher are configured correctly, this error can also occur if the ${fileReference} failed to run on this request (e.g. due to an edge runtime error or platform outage). + +If you verified your configuration and are still seeing this error, there may be a runtime issue or a problem communicating with Clerk. For more details, see https://clerk.com/err/auth-middleware `; From 0920cf9b5083f31c364b64764f6c8bfd2a6369b2 Mon Sep 17 00:00:00 2001 From: Jacek Radko Date: Mon, 9 Mar 2026 14:04:49 -0500 Subject: [PATCH 3/3] Update packages/nextjs/src/server/errors.ts Co-authored-by: Tom Milewski --- packages/nextjs/src/server/errors.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nextjs/src/server/errors.ts b/packages/nextjs/src/server/errors.ts index 59bfa998543..07eb7efdd04 100644 --- a/packages/nextjs/src/server/errors.ts +++ b/packages/nextjs/src/server/errors.ts @@ -28,7 +28,7 @@ export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[ - Your ${fileReference} matcher is configured to match this route or page. - If you are using the src directory, make sure the ${fileReference} file is inside of it. -If you verified your configuration and are still seeing this error, there may be a runtime issue or a problem communicating with Clerk. +If you've verified your configuration and are still seeing this error, there may be a runtime issue or a problem communicating with Clerk. For more details, see https://clerk.com/err/auth-middleware `;