What this usually means
Next.js dynamic imports are client-side by default, but sometimes they're invoked on the server—accidentally or by misconfiguration. SSR execution doesn't have access to browser APIs like `window`, and if a module or component assumes client context, rendering will fail server-side. Sometimes, developers forget to set `ssr: false` when importing client-only modules, especially UI libraries or browser-based utilities. This can result in hydration mismatches, server ReferenceErrors, or even blank components. Non-obvious errors can occur if a package acts differently in Node versus the browser. This category of bug is often environment-dependent, surfacing only in production SSR or CI.
The first ten minutes — establish facts before touching code.
- 1Trigger a full page reload and observe console for 'hydrate failed' and specific stack traces.
- 2Check server logs for ReferenceError or import-time exceptions referencing browser APIs or missing modules.
- 3Search your codebase for all uses of `dynamic(` and verify `ssr` option presence and necessity.
- 4Explicitly reproduce in SSR: run `yarn build && yarn start`, then curl the affected route (not just dev server).
- 5Temporarily wrap suspected components with `<NoSSR>` or run with `ssr: false` and compare results.
- 6Enable Next.js debug logging: set `NEXT_DEBUG=true` and inspect import timings and errors.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchpages/ and components/ directories for all dynamic() calls
- searchnext.config.js for custom webpack configs affecting resolves/aliases
- search.next/server/pages/ for built SSR output
- searchServer logs: `.next/logs/` or PM2/Heroku logs with full stack traces
- searchConsole output for hydration mismatch messages
- searchNetwork tab for failed requests to dynamically imported chunks
Practical causes, not theory. These are the things you will actually find.
- warningForgetting `ssr: false` when dynamically importing client-only code
- warningCode inside dynamic component using `window`, `document`, or other browser APIs during SSR phase
- warningModule path typo or move after import statement added
- warningConditional logic based on `typeof window` missed or bypassed
- warningIncorrect usage of dynamic import syntax (e.g., not passing promise function)
- warningWebpack config or aliasing issues causing module resolve failure server-side
Concrete fix directions. Pick the one that matches your root cause.
- buildAdd `{ ssr: false }` to all dynamic imports reliant on browser APIs
- buildGuard all browser-specific logic inside `useEffect` or client-only hooks
- buildRefactor dynamic components to render null or fallback content on the server
- buildFix imports to use dynamic(() => import('...')) rather than plain import
- buildValidate and fix all custom webpack resolve/alias rules in next.config.js
- buildUpgrade or patch third-party modules that assume a browser context
A fix you cannot prove is a guess. Close the loop.
- verifiedRun `yarn build && yarn start` and check that SSR output matches CSR for affected route
- verifiedNo 'hydrate failed' or mismatch warnings appear in browser dev tools
- verifiedNo `ReferenceError` or missing chunk/module errors in server logs during initial page render
- verifiedComponent displays correctly and interactively after full page reload
- verifiedNo network 404s for dynamic chunks in browser inspector
- verifiedCI passes full SSR render test suite for all routes
Things that make this bug worse or harder to find.
- warningTesting only with `next dev` instead of production build (`next start`)
- warningAssuming client-only state is safe inside dynamic components
- warningLeaving silent SSR errors unaddressed by suppressing console.warn
- warningHardcoding absolute paths or OS-dependent module names in imports
- warningIgnoring hydration mismatch warnings as 'just React being noisy'
- warningRelying solely on client-side navigation for verification
SSR Failure from Dynamic Import of Browser-Only Chart Library
Timeline
- 09:18User reports blank dashboard after deployment.
- 09:23Initial triage: No errors in browser, but server logs show 'ReferenceError: window is not defined'.
- 09:26Find `dynamic(() => import('recharts/BarChart'))` in Dashboard.js without ssr: false.
- 09:30Quick fix: add `{ ssr: false }` to dynamic import. Redeploy to staging.
- 09:32SSR returns HTML, but now 'hydrate failed' warning appears in browser.
- 09:35Wrap chart with fallback loader to sync SSR/CSR output. Warning disappears.
- 09:38Production redeploy; dashboard renders correctly server- and client-side.
The incident started when our dashboard page, which displays several data visualizations, showed up blank for users after a new release. Although the client-side navigation worked, full reloads or direct visits to the dashboard route rendered nothing.
Server logs had a clear error: 'ReferenceError: window is not defined', tracing back to our dynamic import of recharts components. We’d recently switched from static to dynamic imports for the charts but missed adding `ssr: false`, so the server tried (and failed) to render chart components expecting a browser.
After adding the correct `ssr: false` flag and wrapping the dynamic import with a fallback for SSR, the error resolved. Lesson learned: always double-check dynamic imports for browser-only dependencies, especially in SSR contexts.
Root cause
Dynamic import of a browser-dependent module without `ssr: false`, causing SSR to crash.
The fix
Added `{ ssr: false }` to the dynamic import and ensured fallback UI matched SSR expectations.
The lesson
Never assume a library is SSR safe—test SSR builds and always set `ssr: false` for client-only components.
Dynamic imports in Next.js (`next/dynamic`) allow loading modules on demand, but by default, Next.js will try to render these modules on the server unless told otherwise. If the imported component relies on APIs like `window`, `document`, or anything in the browser environment, SSR fails. This is why the `ssr: false` option exists—it tells Next.js to only render that component on the client.
However, it gets tricky: even if a module only uses browser APIs inside effects, bundlers sometimes hoist or evaluate code outside of render scope, leading to ReferenceErrors. Always test in production mode: SSR production builds (`next build && next start`) can behave very differently from development (`next dev`).
Misuse of the dynamic import syntax is rampant: `dynamic(import('...'))` immediately executes the import at build time—a mistake. Correct usage is always `dynamic(() => import('...'))`, which defers the import until invocation.
Forgetting to pass `{ ssr: false }` is the other cardinal sin. If you see modules that access browser APIs, always check for this option. If you’re unsure, read the module’s source or documentation—many UI components do not guard their code for SSR.
Hydration mismatch errors usually mean the SSR output doesn't match what React generates client-side, often because the server rendered nothing or fallback, while the client renders the full component.
This happens if a dynamic import is client-only but its SSR fallback is missing or inconsistent. Set an explicit fallback in the dynamic call, e.g., `dynamic(() => import('./Foo'), { ssr: false, loading: () => <Skeleton /> })`, and ensure skeletons or loaders look identical on both server and client.
Frequently asked questions
When should I use `ssr: false` with Next.js dynamic imports?
Use `ssr: false` whenever a component or module requires browser-only APIs, performs DOM operations, or depends on client context (e.g., window, document, localStorage).
Why do these errors only show up after deployment, not in development?
Next.js's `next dev` runs all code client-side and is more forgiving. Production builds (`next build && next start`) enforce SSR, revealing issues that don't manifest in development.
How can I automate detection of SSR errors from dynamic imports?
Add tests to render key routes with SSR in CI/CD. Run Headless Chrome or Puppeteer against the production build and parse logs for hydration or ReferenceError messages.
Is it possible to have a component partially render server-side and hydrate extra content client-side?
Yes, but the SSR and CSR outputs must structurally match. Use fallback loading states or skeleton UIs for SSR and load extra data or UI on the client to avoid hydration mismatches.