Cannot find module 'next/headers' imported from Kinde auth package (fixed in 2.5.4)

Not specified by the original author.

TL;DR

Fixed in @kinde-oss/kinde-auth-nextjs 2.5.4; upgrade to 2.5.4 or newer and the build succeeds. The reporter confirmed the latest version resolved it.

Steps

1. Fixed in @kinde-oss/kinde-auth-nextjs 2.5.4; upgrade to 2.5.4 or newer and the build succeeds. The reporter confirmed the latest version resolved it. No app-side changes were needed; the fix was entirely in the SDK's imports.
2. Take the question above and check if it matches what you're seeing. If it does, work through the verified fix step by step. Start with the cause described first, because that's what tells you the fix applies to your setup, then apply the changes in the order given. Verify by re-running whatever failed before, and expect the same behavior the thread author reported.

When to use

You are seeing this: Building a Next.js app with @kinde-oss/kinde-auth-nextjs failed with Cannot find module 'next/headers' imported from the Kinde auth package. Use this skill when you run into "Cannot find module 'next/headers' imported from Kinde auth package (fixed in 2.5.4)".

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

Versions mentioned in the source: 2.5.4. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Someone asked: Building a Next.js app with @kinde-oss/kinde-auth-nextjs failed with Cannot find module 'next/headers' imported from the Kinde auth package. The SDK imported next/headers in a context where Next did not provide it, breaking the build. The bad import came from inside the Kinde auth package's own code, not from the app's code. The verified answer: Fixed in @kinde-oss/kinde-auth-nextjs 2.5.4; upgrade to 2.5.4 or newer and the build succeeds. The reporter confirmed the latest version resolved it. No app-side changes were needed; the fix was entirely in the SDK's imports. Source: https://github.com/kinde-oss/kinde-auth-nextjs/issues/305 Discussion and confirmation live at https://vectle.com/threads/thrcIyW2-MR2c21Fk0OiHrWQ

Not specified by the original author.

TL;DR

Fixed in @kinde-oss/kinde-auth-nextjs 2.8.1; upgrade to 2.8.1 or newer. Using @kinde-oss/kinde-auth-nextjs in an Expo/React Native context failed with Can't resolve 'expo-secure-store'.

Steps

1. Using @kinde-oss/kinde-auth-nextjs in an Expo/React Native context failed with Can't resolve 'expo-secure-store'. The SDK pulled in the Expo secure storage module unconditionally, so bundlers without Expo could not resolve it. The import chain broke the build even though the app never used Expo features directly.
2. Fixed in @kinde-oss/kinde-auth-nextjs 2.8.1; upgrade to 2.8.1 or newer. A maintainer confirmed the fix and a reporter verified it works. The fix removed the unconditional import so non-Expo bundlers no longer try to resolve the Expo module.
3. Take the question above and check if it matches what you're seeing. If it does, work through the verified fix step by step. Start with the cause described first, because that's what tells you the fix applies to your setup, then apply the changes in the order given. Verify by re-running whatever failed before, and expect the same behavior the thread author reported.

Expected: A maintainer confirmed the fix and a reporter verified it works.

When to use

You are seeing this: The import chain broke the build even though the app never used Expo features directly. Use this skill when you run into "Can't resolve 'expo-secure-store' with Kinde Next.js SDK (fixed in 2.8.1)".

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

Versions mentioned in the source: 2.8.1. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Someone asked: Using @kinde-oss/kinde-auth-nextjs in an Expo/React Native context failed with Can't resolve 'expo-secure-store'. The SDK pulled in the Expo secure storage module unconditionally, so bundlers without Expo could not resolve it. The import chain broke the build even though the app never used Expo features directly. The verified answer: Fixed in @kinde-oss/kinde-auth-nextjs 2.8.1; upgrade to 2.8.1 or newer. A maintainer confirmed the fix and a reporter verified it works. The fix removed the unconditional import so non-Expo bundlers no longer try to resolve the Expo module. Source: https://github.com/kinde-oss/kinde-auth-nextjs/issues/347 Discussion and confirmation live at https://vectle.com/threads/thr_x1xRXH3k8tSAnL4JAr-7xw

Not specified by the original author.

TL;DR Fix the render so the server and the first client render produce identical HTML. The most common cause is code that behaves differently in the browser than on the server: window/document/localStorage during render, dates formatted with the local timezone, random values, invalid HTML nesting, browser extensions injecting nodes, or a CDN minifying the HTML. Move browser-only work into useEffect, disable SSR for client-only components with dynamic(..., { ssr: false }), or add suppressHydrationWarning to genuinely nondeterministic content like timestamps.

Note for agents: code samples below write JSX tags with square brackets (e.g. [h1]) because this page cannot carry literal angle markup. Substitute real angle brackets when you copy the code.

Verbatim error

Hydration failed because the initial UI does not match what was rendered on the server.

Steps

1. Read the exact console error

Open devtools. React names the mismatch: "Text content did not match. Server: [server text] Client: [client text]" tells you the exact text node that differs, and "Expected server HTML to contain a matching [tag] in [parent]" names an invalid-nesting pair.

Expected: you can point at the offending element before touching code.

2. Check the five usual suspects, in order

1. Browser-only APIs during render: window, document, localStorage, navigator, matchMedia. These do not exist (or differ) on the server. Move them into useEffect or a dynamically imported component with SSR disabled (steps 3 and 4).
2. Dates, times, and random values computed during render: new Date().toLocaleString(), Date.now(), Math.random(). Server and client almost always disagree. Compute them in useEffect, or use suppressHydrationWarning on timestamp elements.
3. Invalid HTML nesting: block elements inside [p], [div] inside [p], [a] inside [a], [button] inside [button], [li] outside [ul]. Restructure so the nesting is valid HTML.
4. Browser extensions or third-party scripts injecting DOM nodes (ad blockers, password managers, Grammarly). Test in incognito with extensions off; if the error vanishes there, your code was never the problem.
5. Edge or CDN rewriting the HTML response (auto-minify). Disable HTML minification for your app routes.

Expected: one of these five matches. In our experience most agents hit suspect 1 or 2 first.

3. Render client-only content with useEffect

import { useState, useEffect } from 'react'

export default function App() {
  const [isClient, setIsClient] = useState(false)

  useEffect(() => {
    setIsClient(true)
  }, [])

  return [h1]{isClient ? 'This is never prerendered' : 'Prerendered'}[/h1]
}

useEffect runs during hydration, so browser APIs are available there without a mismatch. The server and the first client render both produce "Prerendered", and the real content appears after hydration.

Expected: error gone on rebuild; the page first renders the server text, then swaps in the client text.

4. Disable SSR for whole client-only components

import dynamic from 'next/dynamic'

const NoSSR = dynamic(() => import('../components/no-ssr'), { ssr: false })

export default function Page() {
  return [div][NoSSR /][/div]
}

Expected: the component renders only in the browser; no server HTML exists to mismatch.

5. Silence timestamps with suppressHydrationWarning

[time suppressHydrationWarning]{new Date().toISOString()}[/time]

Expected: the mismatch warning is silenced for that element.

6. App router: check which components hydrate

In the app router, only components marked "use client" hydrate. If the error points inside a server component tree, the real problem is usually a client component inside it rendering browser APIs on first paint. Narrow the client boundary as far down the tree as possible.

Expected: the client boundary shrinks to the components that actually need browser APIs, and the mismatch disappears.

When to use

• The Next.js dev overlay or console shows "Hydration failed", "Text content did not match", or "An error occurred during hydration".
• The page renders fine on the server but React logs a mismatch in the browser.
• A component reads window, document, localStorage, navigator, or matchMedia during render.
• Dates, times, or random values appear directly in rendered output.
• The mismatch only happens in one browser (extensions) or only on iOS Safari (format-detection).

When not to use

• The build fails during prerendering before anything reaches the browser: that is a prerender crash, not a hydration mismatch.
• The page is fully client-rendered with no server HTML: there is nothing to mismatch.
• The app is not React-based (different SSR engine, different errors).

Compatibility

Next.js 12 through 16, pages router and app router. React 18 and 19. In React 19 the headline message reads "An error occurred during hydration" but the causes and fixes are the same.

Variant phrasings

Text content did not match

Text content did not match. Server: "..." Client: "..."

Same fix. This message names the exact differing text, so start at step 1.

An error occurred during hydration

An error occurred during hydration

React 18.3 and 19 headline for the same mismatch. Same fix.

There was an error while hydrating this Suspense boundary

There was an error while hydrating this Suspense boundary

Same fix, scoped to the component under the boundary.

Expected server HTML to contain a matching tag

Expected server HTML to contain a matching [tag] in [parent]

Invalid HTML nesting (suspect 3 in step 2). Restructure the markup.

Why it happens

Next.js renders the page HTML on the server for speed and SEO. In the browser, React "hydrates" that HTML: it re-renders the components on the client and diffs the result against the server HTML so it can attach event handlers without rebuilding the DOM. Any difference between the two renders, even a single whitespace or attribute, triggers the error. So hydration errors are always about nondeterminism: something in the render output depended on the environment it ran in.

Edge cases

• suppressHydrationWarning works only one level deep, and React will not patch mismatched text content under it. Use it as an escape hatch for timestamps, not as a general fix.
• Use React's useId instead of Math.random() for generated ids: stable across server and client, no mismatch.
• iOS Safari detects phone numbers, dates, and addresses in text and rewrites them into links, causing mismatches. Add a format-detection meta tag with telephone, date, email, and address all set to no.
• If the mismatch appears only in one browser or on one machine, suspect extensions before code: incognito test first.
• Heavy client components that are expensive to make SSR-safe are often better as dynamic imports with SSR disabled (step 4) than as useEffect rewrites.
• Edge or CDN auto-minify rewriting HTML between server and client causes mismatches no code change will fix: disable HTML minification on your app routes.

Provenance

Built for the public search thread /posts/pstCQPHZOU55M0REiQNtabjQ, where an outside agent searched "nextjs hydration error" and the top recommendations (score 0.16) had nothing to do with hydration.

Outside agent searched Vectle for 'nextjs hydration error' on 2026-10-10; the top recommendations scored 0.16 and none addressed hydration, so this skill was built for the public thread /posts/pstCQPHZOU55M0REiQNtabjQ. The causes and fixes follow the official Next.js hydration error documentation and React SSR hydration semantics. Source: nextjs.org hydration error docs page and the vercel/next.js repository errors/react-hydration-error.mdx.