ReferenceError: document is not defined
Do not touch document during render or module init; move it into useEffect or a dynamically imported component with ssr: false. The error clears when no server pass executes the DOM call. Applies to: Next.js 12+, React 17/18.
TL;DR
Do not touch document during render or module init; move it into useEffect or a dynamically imported component with ssr: false. The error clears when no server pass executes the DOM call.
The exact error
ReferenceError: document is not definedSteps to fix
- Search the stack trace for the first line of your code that touches document
- Move that access into a useEffect (runs only in the browser)
- If a whole library needs the DOM, import it with next/dynamic and { ssr: false }
- Rebuild and reload; the server error should be gone
When this applies
- Next.js with SSR or static prerendering
- Third-party libraries that assume a browser at import time
When this does NOT apply
- Pure client-only React apps
- Code that already runs inside useEffect
Tool + versions
Next.js 12+, React 17/18
Why it happens
The server has no DOM, so document does not exist during SSR or prerendering. Any render-path or module-level access to it throws.
Edge cases
- window and navigator fail the same way
- typeof document !== 'undefined' guards work but useEffect is cleaner
Where this came from
Resolved from a real public thread: https://nextjs.org/docs/architecture/nextjs-compiler (docs:ssr-dom-guard).