A Leaflet map crashes the Next.js build or shows up broken
ReferenceError: window is not definedShort answer
Leaflet reads window as soon as it loads, and Next.js renders Client Components on the server first, where window does not exist. Load the map component with next/dynamic and ssr set to false, inside a Client Component. If the map then shows but looks broken, import leaflet.css and give the container a height.
Fix it fast
1Find out which cause you have
Read the stack trace of the error. If it starts inside leaflet or react-leaflet while a page renders, the map is being imported on the server.
npm run build 2>&1 | grep -n -B2 -A8 "window is not defined"2Match what you see, then jump to its fix
- 1
ReferenceError: window is not defined during next build or on the first page loadThe map component is rendered on the serverFix - 2
An error says ssr: false is not allowed with next/dynamic in Server Componentsssr: false is used in a Server ComponentFix - 3
No error, but the map area is empty or has no heightThe map loads but is blankFix
- 1
What does the error look like?
ReferenceError: window is not definedwindow is not defined
Cause 1 of 3
The map component is rendered on the server
1Check
Client Components are prerendered to HTML on the server. Browser APIs such as window are not available there, so any module that touches window at import time fails.
grep -rn "react-leaflet\|from 'leaflet'" app components src 2>/dev/null2Fix
Import the map with next/dynamic and ssr: false. The option works only in a Client Component, so put the call in a file that starts with 'use client'.
// app/map-loader.jsx
'use client'
import dynamic from 'next/dynamic'
const Map = dynamic(() => import('../components/Map'), {
ssr: false,
loading: () => <p>Loading map...</p>,
})
export default function MapLoader() {
return <Map />
}3Verify
The build finishes and the page renders the map in the browser.
npm run buildConfirmed by nextjs.org
Cause 2 of 3
ssr: false is used in a Server Component
1Check
The option is not supported in Server Components, so a dynamic call in a plain page.js without 'use client' fails.
head -n 3 app/page.js2Fix
Move the dynamic import into a small Client Component, as in the loader above, and render that component from the page.
// app/page.js (Server Component)
import MapLoader from './map-loader'
export default function Page() {
return <MapLoader />
}3Verify
The error is gone on the next build.
npm run buildConfirmed by nextjs.org
Cause 3 of 3
The map loads but is blank
1Check
Leaflet needs its stylesheet and a container with a height. A div with no height has nothing to draw into.
grep -rn "leaflet.css\|MapContainer" app components src 2>/dev/null2Fix
Import the stylesheet in the map component and give the container an explicit height.
// components/Map.jsx
'use client'
import 'leaflet/dist/leaflet.css'
import { MapContainer, TileLayer } from 'react-leaflet'
export default function Map() {
return (
<MapContainer center={[51.505, -0.09]} zoom={13} style={{ height: 400 }}>
<TileLayer
attribution="© OpenStreetMap contributors"
url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
/>
</MapContainer>
)
}3Verify
Reload the page: the tiles fill a 400 pixel tall box.
npm run devConfirmed by leafletjs.com
How do I stop it coming back?
- Treat every browser-only library the same way: load it in a Client Component with ssr: false, or touch it inside useEffect.
- Set the map container height in CSS or inline style when you create the component.
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