withAuth Errors Out Claiming Route Not Covered by Middleware Despite Matcher Including It

[Iweisc]

Describe the bug
Calling withAuth in /api/auth/session route throws "You are calling 'withAuth' on a route that isn't covered by the AuthKit middleware" error, even when middleware matcher includes /api/:path* and custom middleware passes x-workos-middleware header.

To Reproduce

1. Set up Next.js app with AuthKit.
2. Create middleware.ts with authkit and matcher including /api/:path*.
3. Define GET handler in app/api/auth/session/route.ts using withAuth.
4. Run npm run dev and access root path, triggering session fetch.
5. See error in logs.

Expected behavior
withAuth should retrieve session without middleware coverage error when route is matched.

Screenshots
➜ user-dashboard git:(feature/global_search_and_labels) ✗ npm run dev

user-dashboard@0.1.0 dev
next dev -p 3001

▲ Next.js 14.2.18

• Local: http://localhost:3001
• Environments: .env.local

✓ Starting...
✓ Ready in 1444ms
○ Compiling / ...
✓ Compiled / in 608ms (405 modules)
✓ Compiled in 108ms (405 modules)
Each child in a list should have a unique "key" prop.

Check the render method of Head. See https://react.dev/link/warning-keys for more information.
GET / 200 in 835ms
✓ Compiled /api/auth/session in 459ms (730 modules)

========== SESSION API START ==========
[2025-12-28T08:01:38.561Z] GET /api/auth/session called
[2025-12-28T08:01:38.561Z] Cookies in request: [ 'wos-session' ]
[2025-12-28T08:01:38.561Z] WorkOS session cookie found: true
[2025-12-28T08:01:38.561Z] WorkOS session cookie name: wos-session
[2025-12-28T08:01:38.561Z] WorkOS session cookie value length: 1852
[2025-12-28T08:01:38.561Z] x-workos-session header present: false
[2025-12-28T08:01:38.561Z] x-workos-middleware header: null
[2025-12-28T08:01:38.561Z] Calling withAuth()...
[2025-12-28T08:01:38.561Z] Error in withAuth(): Error: You are calling 'withAuth' on a route that isn't covered by the AuthKit middleware. Make sure it is running on all paths you are calling 'withAuth' from by updating your middleware config in 'middleware.(js|ts)'.
at getSessionFromHeader (webpack-internal:///(rsc)/../../node_modules/.pnpm/@workos-inc+authkit-nextjs@2.12.2_next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react_piia6ohisnywdlj5lqdw5gzpxu/node_modules/@workos-inc/authkit-nextjs/dist/esm/session.js:436:15)
at async withAuth (webpack-internal:///(rsc)/../../node_modules/.pnpm/@workos-inc+authkit-nextjs@2.12.2_next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react_piia6ohisnywdlj5lqdw5gzpxu/node_modules/@workos-inc/authkit-nextjs/dist/esm/session.js:385:21)
at async GET (webpack-internal:///(rsc)/./app/api/auth/session/route.ts:31:28)
at async /home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:55831
at async eO.execute (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:46527)
at async eO.handle (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:57165)
at async doRender (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1353:42)
at async cacheEntry.responseCache.get.routeKind (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1575:28)
at async DevServer.renderToResponseWithComponentsImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1483:28)
at async DevServer.renderPageComponent (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1911:24)
at async DevServer.renderToResponseImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1949:32)
at async DevServer.pipeImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:921:25)
at async NextNodeServer.handleCatchallRenderRequest (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/next-server.js:272:17)
at async DevServer.handleRequestImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:817:17)
at async /home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/dev/next-dev-server.js:339:20
[2025-12-28T08:01:38.561Z] Error name: Error
[2025-12-28T08:01:38.561Z] Error message: You are calling 'withAuth' on a route that isn't covered by the AuthKit middleware. Make sure it is running on all paths you are calling 'withAuth' from by updating your middleware config in 'middleware.(js|ts)'.
[2025-12-28T08:01:38.561Z] Error stack: Error: You are calling 'withAuth' on a route that isn't covered by the AuthKit middleware. Make sure it is running on all paths you are calling 'withAuth' from by updating your middleware config in 'middleware.(js|ts)'.
at getSessionFromHeader (webpack-internal:///(rsc)/../../node_modules/.pnpm/@workos-inc+authkit-nextjs@2.12.2_next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react_piia6ohisnywdlj5lqdw5gzpxu/node_modules/@workos-inc/authkit-nextjs/dist/esm/session.js:436:15)
at async withAuth (webpack-internal:///(rsc)/../../node_modules/.pnpm/@workos-inc+authkit-nextjs@2.12.2_next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react_piia6ohisnywdlj5lqdw5gzpxu/node_modules/@workos-inc/authkit-nextjs/dist/esm/session.js:385:21)
at async GET (webpack-internal:///(rsc)/./app/api/auth/session/route.ts:31:28)
at async /home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:55831
at async eO.execute (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:46527)
at async eO.handle (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:57165)
at async doRender (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1353:42)
at async cacheEntry.responseCache.get.routeKind (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1575:28)
at async DevServer.renderToResponseWithComponentsImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1483:28)
at async DevServer.renderPageComponent (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1911:24)
at async DevServer.renderToResponseImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:1949:32)
at async DevServer.pipeImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:921:25)
at async NextNodeServer.handleCatchallRenderRequest (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/next-server.js:272:17)
at async DevServer.handleRequestImpl (/home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/base-server.js:817:17)
at async /home/sertdev/Projects/mono/node_modules/.pnpm/next@14.2.18_@playwright+test@1.57.0_react-dom@19.2.3_react@19.2.3__react@19.2.3/node_modules/next/dist/server/dev/next-dev-server.js:339:20
========== SESSION API END (ERROR) ==========

GET /api/auth/session 200 in 580ms

Desktop (please complete the following information):

• OS: Linux (Fedora 43)
• Browser: Zen (server-side)
• authkit-nextjs version: 2.12.2
• Next.js version: 14.2.18

Additional context
Middleware code:

import { authkit } from "@workos-inc/authkit-nextjs";  
import { NextRequest, NextResponse } from "next/server";  
const unauthenticatedPaths = [  
"/",  
"/auth/login",  
"/auth/callback",  
"/api/auth/callback",  
"/api/auth/signin-url",  
"/api/auth/session",  
];  
function isUnauthenticatedPath(pathname: string): boolean {  
return unauthenticatedPaths.some(  
(p) => pathname === p || pathname.startsWith(p + "/"),  
  );  
}  
export default async function middleware(request: NextRequest) {  
const { pathname } = request.nextUrl;  
const {  
session,  
headers: authkitHeaders,  
authorizationUrl,  
} = await authkit(request, {  
debug: true,  
});  
if (!isUnauthenticatedPath(pathname) && !session.user) {  
const response = NextResponse.redirect(authorizationUrl!);  
for (const [key, value] of authkitHeaders) {  
if (key.toLowerCase() === "set-cookie") {  
response.headers.append(key, value);  
} else {  
response.headers.set(key, value);  
}  
}  
return response;  
}  
const requestHeaders = new Headers(request.headers);  
for (const [key, value] of authkitHeaders) {  
if (key.toLowerCase() !== "set-cookie") {  
requestHeaders.set(key, value);  
}  
}  
requestHeaders.set("x-workos-middleware", "true");  
const response = NextResponse.next({  
request: { headers: requestHeaders },  
});  
for (const [key, value] of authkitHeaders) {  
if (key.toLowerCase() === "set-cookie") {  
response.headers.append(key, value);  
}  
}  
return response;  
}  
export const config = {  
matcher: [  
"/",  
"/sessions/:path*",  
"/auth/:path*",  
"/api/:path*",  
"/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",  
  ],  
};  

Error persists in debug logs showing x-workos-middleware header: null in session API.

[Iweisc]

Upgraded to next js 16.1 still the same issue.

[Iweisc]

Fixed the issue, #353