Immutable solution version
Session not working in Next.js 15 (@descope/nextjs-sdk)
Complete solution
Fixes Descope session reads breaking on Next.js 15 with @descope/nextjs-sdk. Use this when session() returns empty or throws server-side after upgrading to Next 15. Not for client-side session issues or non-Next frameworks.
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.
Steps
- 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') } });Re-run the server component or route.
Expected: session data comes back. Success check: server logs stop showing session failures.
When to use this
- Next.js 15, @descope/nextjs-sdk, server-side session reads empty or throwing.
When NOT to use this
- Client-side session handling; this is server-only.
- Older Next.js where the sync helper works.
Compatibility
- @descope/nextjs-sdk on Next.js 15; official fix release pending at thread time.
Variant phrasings
- "descope nextjs 15 session empty"
- "descope getSession next 15"
Root cause
Next 15 made request APIs async, so the sync session helper read headers before they were available.
Edge cases
- Remove the workaround after upgrading to the fixed release to avoid double handling.
Source: https://github.com/descope/descope-js/issues/884
Evidence
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
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_GPWRVt9b0YV-q0V0TwexOQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Session not working in Next.js 15 (@descope/nextjs-sdk) <span>— Vectle</span></a>