Build a web map with Leaflet: troubleshooting guide

What you need before debugging

Before debugging a complex application, create a minimal reproduction in a plain HTML file or a small isolated route. Keep the first version limited to one map container, one Leaflet version, one tile layer, and a fixed geographic center. This establishes whether the failure is in Leaflet initialization or in your framework, build system, data pipeline, or custom controls.

Use a browser with developer tools. The Console identifies JavaScript exceptions such as `L is not defined`, while the Network panel shows whether Leaflet assets and tile images return successfully. Confirm that the page is served over HTTP during development rather than opened directly with a `file://` URL when your data or tiles require browser requests.

• •A reproducible browser error and the first relevant console message.
• •The Leaflet version loaded by the page; the official 1.9.4 reference documents the stable API covered by the examples used here. (leafletjs.com)
• •A map container with an explicit height and a unique identifier.
• •A known coordinate pair and a known tile-service URL.
• •A clear distinction between basemap tiles, application overlays, and computed geographic results.

Step 1: reduce the map to a known-good baseline

Replace the application temporarily with the smallest complete page. The order matters: load Leaflet CSS, create a container with height, load Leaflet JavaScript, then initialize the map after the container exists. The following example follows the structure of the official Leaflet quick start while using HTTPS for the OpenStreetMap tile URL. (leafletjs.com)

• •If the page shows a completely blank region with no controls, inspect the container dimensions first.
• •If the browser reports `L is not defined`, the JavaScript file did not load, loaded after your initialization code, or was blocked.
• •If controls appear but tiles do not, initialization succeeded and the problem is probably the tile request, attribution configuration, provider policy, or network environment.
• •If the map appears only after resizing the browser, call `map.invalidateSize()` after the containing element becomes visible or changes dimensions. This is especially relevant for tabs, dialogs, accordions, and dynamically sized panels.

Step 2: diagnose tiles, attribution, and provider behavior

A Leaflet map can be functioning correctly while its basemap is unavailable. Inspect one failed tile request in the Network panel. A `404` usually indicates a malformed URL or unsupported path. A `401` or `403` points to authentication, referrer, origin, or provider-policy issues. A request that remains pending can indicate connectivity, a blocked domain, or a service-side problem. Mixed-content warnings occur when an HTTPS page requests an HTTP tile URL.

For OpenStreetMap's standard raster tiles, the current policy specifies `https://tile.openstreetmap.org/{z}/{x}/{y}.png`, visible attribution, a valid identifying request context, normal browser referrers, respect for cache headers, and no bulk downloading or offline prefetching. The service is best-effort and does not provide an SLA. Do not treat the public tile server as an unlimited production CDN. (operations.osmfoundation.org)

• •Check the exact request URL, response status, response headers, and browser-referrer behavior.
• •Confirm that the attribution is visible and not hidden under another control.
• •Do not use a tile URL copied from an unrelated map application unless its provider terms permit reuse.
• •Do not solve a slow public service by adding aggressive prefetching or disabling browser caching.
• •If the basemap is optional, test the application with a temporary local or approved alternative layer so overlay debugging can continue.

Step 3: validate coordinates, layers, and GeoJSON

Leaflet's geographic APIs use latitude and longitude in the order `[lat, lng]`. A common failure is passing GeoJSON coordinates directly into a marker without accounting for GeoJSON's `[longitude, latitude]` order. The result may be a feature rendered in the wrong country, outside the visible map, or at an invalid latitude. Test one known point before loading a large dataset.

For a GeoJSON overlay, validate the response before adding it to the map. Confirm that the response is valid JSON, has `type: "FeatureCollection"` or a supported GeoJSON object type, contains geometries rather than null values where expected, and uses the coordinate reference system your application assumes. Modern GeoJSON workflows generally use WGS 84 longitude-latitude coordinates, but your upstream service should state its convention explicitly rather than relying on guesswork.

• •Log the first feature and its coordinates before rendering the full collection.
• •Use `map.getBounds()` or a layer's bounds to check whether the data is outside the initial viewport.
• •Check for `null` geometries and empty coordinate arrays.
• •Use a stable identifier in feature properties so popup and click behavior can be traced back to source records.
• •Avoid adding tens of thousands of individual DOM-heavy markers without clustering, simplification, server-side filtering, or a different rendering strategy.

Step 4: troubleshoot interaction, layout, and production differences

When the map renders but interaction fails, isolate event handling from data loading. Attach a simple click listener to the map and show the clicked coordinates. If that works, the problem is probably in the overlay event handler, popup content, or application state. Leaflet's official quick start demonstrates map click events and popups as separate concerns, which is a useful debugging pattern. (leafletjs.com)

For maps inside hidden elements, initialize after the element is visible or call `invalidateSize()` after it becomes visible. For maps inside flexbox or grid layouts, inspect the computed height of every parent. A child with `height: 100%` cannot acquire useful height if its ancestors have no defined height.

• •Verify the map container has nonzero width and height at initialization and after route changes.
• •Ensure the map is created once per DOM element and destroyed or detached correctly when a component unmounts.
• •Test tile and data requests from the deployed origin, not only from localhost.
• •Keep popups concise and escape or sanitize untrusted text before inserting HTML.
• •Record map center, zoom, layer identifiers, data timestamp, and provider configuration when diagnosing user reports.