RSC Error with cookies() in layout.tsx when using basePath in Next.js 16

[Heet-Bhalodiya]

Link to the code that reproduces this issue

https://github.com/Heet-Bhalodiya/mui-next-test

To Reproduce

Link to reproduction

Repository: https://github.com/Heet-Bhalodiya/mui-next-test
Deployed URL: https://mui-next-test-ten.vercel.app/test/en

Describe the Bug

After upgrading to Next.js 16.0.1, using cookies() in layout.tsx causes RSC (React Server Components) errors in production when a basePath is configured. This creates an impossible dilemma for implementing server-side theme persistence with system preference support.

The Dilemma

There are two approaches to implement theme persistence, but both have critical issues:

Approach 1: Using cookies() in layout (Current Implementation)

✅ Pros:

• Theme persists correctly across page refreshes
• Server knows the user's theme preference
• System mode can be stored and retrieved

❌ Cons:

• Causes RSC server errors in production when basePath is configured
• Forces all routes to be dynamic (removes static optimization)
• Cannot use generateStaticParams() because cookies() makes the entire layout dynamic

Approach 2: Using generateStaticParams() without cookies

✅ Pros:

• No RSC errors
• Routes can be statically generated

❌ Cons:

• Server has no knowledge of user's theme preference
• If server defaults to 'light' but user's system is 'dark', the page renders light first, then switches to dark

Would appreciate guidance on:

1. Is this a bug or expected behavior?
2. What's the recommended way to implement server-side theme persistence in Next.js 16 with basePath?
3. Is there a way to use cookies() without triggering RSC errors in this configuration?

Current vs. Expected behavior

Current Issue

When deploying with basePath configured and using cookies() in the root layout, the application throws RSC errors in production (see screenshot below).

Error Context:

• Happens in production deployment
• Only when basePath is configured
• Started happening after Next.js 16 update (it worked as expected till next v15)

Expected Behavior

1. Should be able to use cookies() in root layout without RSC errors when basePath is configured
2. Should be able to read server-side cookies to determine theme preference and avoid FOUC
3. Should support system preference detection on the server side
4. Static generation should be optional when dynamic features (like cookies) are required

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.1.0: Mon Oct 20 19:32:56 PDT 2025; root:xnu-12377.41.6~2/RELEASE_ARM64_T8132
  Available memory (MB): 16384
  Available CPU cores: 10
Binaries:
  Node: 22.12.0
  npm: 11.4.2
  Yarn: 1.22.22
  pnpm: 10.11.0
Relevant Packages:
  next: 16.0.1 // There is a newer version (16.0.3) available, upgrade recommended! 
  eslint-config-next: N/A
  react: 19.2.0
  react-dom: 19.2.0
  typescript: 5.9.3
Next.js Config:
  output: N/A
 ⚠ There is a newer version (16.0.3) available, upgrade recommended! 
   Please try the latest canary version (`npm install next@canary`) to confirm the issue still exists before creating a new issue.
   Read more - https://nextjs.org/docs/messages/opening-an-issue

Which area(s) are affected? (Select all that apply)

Cookies, Dynamic Routes

Which stage(s) are affected? (Select all that apply)

Vercel (Deployed), next build (local)

Additional context

No response

[Heet-Bhalodiya]

Any updates??

Edit by maintainer bot: Comment was automatically minimized because it was considered unhelpful. (If you think this was by mistake, let us know). Please only comment if it adds context to the issue. If you want to express that you have the same problem, use the upvote 👍 on the issue description or subscribe to the issue for updates. Thanks!

[rosbitskyy]

Fix RSC Error with cookies() in layout.tsx when using basePath

Problem

When using basePath configuration and cookies() in layout.tsx, Next.js 16.0.1+ throws RSC (React Server Components) errors in production. This was a regression from Next.js 15, where it worked correctly.

Root Cause

In handleRSCRequest method, when normalizing RSC requests, the basePath was not being removed from parsedUrl.pathname after normalization. This caused the request store to be created with an incorrect URL path, preventing cookies() from finding the proper request context.

For example:

• Request comes as /basePath/page.rsc
• After RSC normalization: /basePath/page (basePath still present)
• Request store created with incorrect pathname
• cookies() fails to find request context → RSC error

Solution

Changes Made

1. Fixed handleRSCRequest in packages/next/src/server/base-server.ts

   • Added basePath removal after RSC normalization for both:
     • Segment prefetch RSC requests (lines 589-595)
     • Regular RSC requests (lines 611-617)
   • Ensures parsedUrl.pathname has basePath stripped before request store creation

2. Added test case

   • Created test layout: test/e2e/app-dir/app-routes/app/test-layout-cookies/layout.tsx
   • Created test page: test/e2e/app-dir/app-routes/app/test-layout-cookies/page.tsx
   • Added test in app-custom-routes.test.ts to verify cookies() works with basePath

Code Changes

// In handleRSCRequest, after RSC normalization:
if (this.nextConfig.basePath) {
  parsedUrl.pathname = removePathPrefix(
    parsedUrl.pathname,
    this.nextConfig.basePath
  )
}

How to Test

Manual Testing

1. Set up a Next.js app with basePath:

   // next.config.js
   module.exports = {
     basePath: 'https://github.com/docs',
   }

2. Create a layout that uses cookies():

   // app/layout.tsx
   import { cookies } from 'next/headers'
   
   export default async function RootLayout({ children }) {
     const cookieStore = await cookies()
     const theme = cookieStore.get('theme')
     
     return (
       <html>
         <body>{children}</body>
       </html>
     )
   }

3. Test in production:

   npm run build
   npm start

4. Verify:

   • Navigate to http://localhost:3000/docs (or your basePath)
   • Should render without RSC errors
   • Cookies should be accessible in layout

Automated Testing

Run the existing test suite:

# Run the specific test
npm test -- test/e2e/app-dir/app-routes/app-custom-routes.test.ts

# Or run with basePath environment variable
BASE_PATH=/docs npm test -- test/e2e/app-dir/app-routes/app-custom-routes.test.ts

The test cookies in layout with basePath verifies:

• Layout can use cookies() with basePath configured
• Cookies are correctly read and rendered
• No RSC errors occur

Test Case Details

The test case:

1. Fetches /test-layout-cookies with a cookie header
2. Verifies the response status is 200
3. Checks that the cookie value is correctly rendered in the HTML

Verification Checklist

• Fix applied to both RSC request types (segment prefetch and regular)
• Test case added and passing
• No linter errors
• Code follows Next.js conventions
• Works in production build mode

Related Issue

Fixes: #86284

[Heet-Bhalodiya]

Hey @rosbitskyy,

Thanks for the fix! 😊

Quick question - why did this only happen in Next.js 16 when everything worked fine in Next.js 15?

And will this be included in the upcoming release? 🤔

[rosbitskyy]

Hey @Heet-Bhalodiya! 👋

Great question! This regression happened because Next.js 16 introduced changes to how RSC requests are handled in production (minimal mode). The RSC pathname normalizer was added to strip .rsc suffixes from URLs, but it didn't account for basePath removal - that step was happening later in the request flow, after the request store was already created. This caused cookies() to fail finding the proper request context.

In Next.js 15, RSC requests were handled differently, so this edge case didn't occur.

Regarding the release: This PR will need to be reviewed by Next.js maintainers/contributors who will decide if it gets merged and included in an upcoming release. The fix is ready and includes tests, so hopefully it can make it into the next patch/minor release! 🤞

Thanks for reporting the issue! 🙏

[Heet-Bhalodiya]

Hey @rosbitskyy,

Why this has not yet been merged and released? Do you have any updates or insight on the status?

[rosbitskyy]

Don't join the merge because I accidentally merged all 17 updates into one PR. GitHub agents went a bit overboard. пт, 12 груд. 2025 р. о 06:17 Heet Bhalodiya ***@***.***> пише:

…

*Heet-Bhalodiya* left a comment (vercel/next.js#86284) <#86284 (comment)> Hey @rosbitskyy <https://github.com/rosbitskyy>, Why this has not yet been merged and released? Do you have any updates or insight on the status? — Reply to this email directly, view it on GitHub <#86284 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AB55YQXWU5TLNQJ3AYSFWAD4BI6UNAVCNFSM6AAAAACMRNO6HKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMNBUHAZTONJXGE> . You are receiving this because you were mentioned.Message ID: <vercel/next .***@***.***>

-- с уважением, розбицкий руслан +38 067 4 111 112 +38 063 062 4000 skype:rus_lan_st icq uin:183 54 183