Using a context provider or hook in a Next.js Server Component fails
Error: React Context is unavailable in Server ComponentsShort answer
Layouts and pages in the App Router are Server Components, and React context is not supported there. Move createContext and the provider into a file that starts with 'use client', accept children, and render that wrapper in the layout. Third-party providers need the same wrapper.
Fix it fast
1Find out which cause you have
Find the file the error points to, then see whether it creates a context, renders a provider, or calls useContext without 'use client' on its first line.
grep -rLn "use client" app/ | xargs grep -ln "createContext\|useContext\|Provider"2Match what you see, then jump to its fix
- 1
The error is raised in layout.tsx or page.tsx, which have no 'use client' line.createContext or a provider lives in a Server ComponentFix - 2
The failing import is from a package (a session, query or UI library), used straight in the layout.A third-party provider has no 'use client' directiveFix - 3
The page uses useContext, useState or an effect directly and carries no 'use client' line.A hook is called in a Server ComponentFix
- 1
What does the error look like?
Error: React Context is unavailable in Server ComponentsA third-party component throws an error when used directly in a layout or page
Cause 1 of 3
createContext or a provider lives in a Server Component
1Check
Next.js documents that React context is not supported in Server Components, and layouts and pages are Server Components by default.
head -n 5 app/layout.tsx2Fix
Create a small Client Component that holds the context and accepts children, then import it into the layout.
// app/theme-provider.tsx
'use client'
import { createContext } from 'react'
export const ThemeContext = createContext({})
export default function ThemeProvider({ children }: { children: React.ReactNode }) {
return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
}
// app/layout.tsx
import ThemeProvider from './theme-provider'
// ...<body><ThemeProvider>{children}</ThemeProvider></body>3Verify
Start the dev server and open a page that reads the context in a Client Component.
npm run devConfirmed by nextjs.org
Cause 2 of 3
A third-party provider has no 'use client' directive
1Check
A package component that uses client-only features, but whose module lacks the 'use client' directive, fails when a Server Component renders it.
grep -rn "from 'next-auth\|from '@tanstack" app/layout.tsx2Fix
Wrap the package component in your own file that has 'use client', and import that wrapper in the Server Component.
// app/providers.tsx
'use client'
import { Carousel } from 'acme-carousel'
export default Carousel3Verify
The layout now imports the wrapper instead of the package, and the error is gone after a restart.
npm run devConfirmed by nextjs.org
Cause 3 of 3
A hook is called in a Server Component
1Check
State, effects and custom hooks need a Client Component. Data that only needs to be fetched can stay on the server.
grep -n "useContext\|useState\|useEffect" app/dashboard/page.tsx2Fix
Move the part that uses the hook into a Client Component and pass server data to it through props. Props must be serializable.
// app/ui/like-button.tsx
'use client'
import { useState } from 'react'
export default function LikeButton({ likes }: { likes: number }) { /* ... */ }3Verify
Render the new Client Component from the page and reload.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Keep layouts and pages as Server Components and put 'use client' only on the small interactive files.
- Render providers as deep in the tree as you can, wrapping children rather than the whole html element.
- Collect all providers in one providers file so each new library has one obvious place.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb apps
next/link throws React.Children.only on its children
Error: React.Children.only expected to receive a single React element child.
React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.
3 causes, each with a fixWeb apps
Hydration failed after adding next-themes dark mode
Console reports a server and client mismatch on the html element
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.
3 causes, each with a fix