Session not working in Next.js 15 (@descope/nextjs-sdk)

TL;DR

Upgrade to the release with the official Next 15 fix once available and drop the workaround.

Steps

1. TL;DR: on Next.js 15, reading the Descope session server-side via session() from @descope/nextjs-sdk breaks because the helper was sync while Next 15 requires awaiting headers() and other request APIs. Until the fixed release, use the async getSession helper from @descope/nextjs-sdk/server: await headers() from next/headers, build a request object carrying the x-descope-session header, and pass it to getSession(req). Descope staff posted exactly this pattern. Upgrade to the release with the official Next 15 fix once available and drop the workaround.
2. Replace the sync session() call with the async pattern:

import { headers } from 'next/headers';
import { getSession } from '@descope/nextjs-sdk/server';

const h = await headers();
const session = await getSession({ headers: { 'x-descope-session': h.get('x-descope-session') } });

3. Re-run the server component or route.
4. Expected: session data comes back. Success check: server logs stop showing session failures.
5. - Next.js 15, @descope/nextjs-sdk, server-side session reads empty or throwing.
6. - Client-side session handling; this is server-only.

• Older Next.js where the sync helper works.

7. - @descope/nextjs-sdk on Next.js 15; official fix release pending at thread time.
8. Next 15 made request APIs async, so the sync session helper read headers before they were available.
9. - Remove the workaround after upgrading to the fixed release to avoid double handling.

When to use

You are seeing this: Descope staff posted exactly this pattern. Use this skill when you run into "Session not working in Next.js 15 (@descope/nextjs-sdk)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

Next 15 made request APIs async, so the sync session helper read headers before they were available.

Asked in the thread (https://vectle.com/threads/thr_I-R4Z9d0excc5eNREX65Rg): On Next.js 15, reading the Descope session server-side via session() from @descope/nextjs-sdk broke: the helper was sync while Next 15 requires awaiting headers() and other request APIs, so session data came back empty or threw. Descope reproduced the issue and worked on a fix. Affected apps saw repeated session failures piling up in their server logs. Verified resolution: Until the fixed release, use the async getSession helper from @descope/nextjs-sdk/server as a workaround: await headers() from next/headers, build a request object carrying the x-descope-session header, and pass it to getSession(req). Descope staff posted exactly this pattern and it restores session reads on Next 15. Upgrade @descope/nextjs-sdk to the release containing the official Next 15 fix once available so the workaround can be removed. Source: https://github.com/descope/descope-js/issues/884