Build a web map with MapLibre: troubleshooting guide

What you need before debugging

Create a minimal reproducible page rather than debugging inside a large application first. You need a browser with developer tools, a working Node.js project or static HTML page, the maplibre-gl package or an equivalent browser module, a map container with an explicit height, and either a known-good style URL or a local style document. MapLibre’s official quickstart uses the MapLibre stylesheet, a map container with a defined height, an ES module import, a style URL, and a starting camera. (maplibre.org)

Keep four concerns separate while diagnosing: the renderer, the style, the geographic source, and application code that changes the map. If a baseline map works, add one custom source or layer at a time. If the baseline fails, do not begin by inspecting spatial joins, tile-generation pipelines, or application state. First establish that the browser can create a map and retrieve the style resources.

• •Browser developer tools with Console and Network panels open.
• •A map container with a nonzero width and height.
• •A style document that is reachable from the browser.
• •A clear coordinate convention: geographic examples use [longitude, latitude].
• •A small test dataset before attempting millions of features or high-frequency updates.
• •Attribution and usage terms for every basemap, tile source, imagery layer, font, sprite, or overlay.

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

Begin with the smallest page that can render a map. This example follows the initialization pattern in MapLibre’s official documentation and uses its public demonstration style. Treat the demonstration style as a diagnostic dependency, not as a production basemap, service-level guarantee, or data-licensing decision. (maplibre.org)

The goal of this step is not to prove that your final style or data pipeline works. It is to answer narrower questions: does the container have dimensions, can the browser create the rendering context, can the page load the MapLibre CSS and JavaScript, and can the browser retrieve and parse one style document?

• •Confirm that the MapLibre stylesheet and JavaScript module are loaded.
• •Give the map element an explicit height; width alone is not enough for a visible map.
• •Open the console and watch for style, worker, WebGL, or network errors.
• •Check that the style request returns JSON rather than an HTML error page.
• •Only after the baseline renders should you replace the style or add application data.

Minimal baseline

Save this as a standalone HTML file and serve it through a local HTTP server rather than relying on file:// behavior. The explicit height, fixed camera, style URL, load handler, and error handler make the first failure easier to identify. The style URL and module pattern are based on the official quickstart. (maplibre.org)

• •<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^6.8.0/dist/maplibre-gl.css" /> <style> html, body { margin: 0; height: 100%; } #map { width: 100%; height: 100%; min-height: 400px; } </style> </head> <body> <div id="map" aria-label="Interactive map"></div> <script type="module"> import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.8.0/dist/maplibre-gl.mjs'; const map = new maplibregl.Map({ container: 'map', style: 'https://demotiles.maplibre.org/globe.json', center: [0, 0], zoom: 2 }); map.on('load', () => console.log('Map style loaded')); map.on('error', event => console.error('MapLibre error', event.error)); </script> </body> </html>

Step 2: diagnose styles, sources, and layers

A MapLibre style is a JSON document that defines what data to draw, the order in which to draw it, and how to style it. Its root properties include sources and layers, while camera properties such as center, zoom, pitch, and bearing can provide initial view defaults. (maplibre.org)

A style can load successfully while a specific layer remains invisible. Inspect the style in the Network panel or fetch it directly, then check source IDs, source-layer names, geometry types, filters, zoom limits, layout properties, and paint properties. The Style Specification states that layers generally refer to sources, and vector-tile layers must identify the internal source layer. (maplibre.org)

• •If the style request returns 404, 403, HTML, or invalid JSON, fix the style URL or server response first.
• •If the style loads but labels, icons, or linework are absent, inspect glyph, sprite, and tile URLs separately.
• •If a vector layer is empty, verify source-layer exactly, including capitalization and punctuation.
• •Temporarily remove filters, minzoom, maxzoom, opacity, and data-driven expressions to prove that features can render.
• •Use a simple fill, line, or circle layer before debugging symbol placement, fonts, icons, or complex expressions.
• •Add sources and layers after the style has loaded, and re-add them after a style replacement if the application changes styles.

Step 3: validate coordinates and GeoJSON

When a custom overlay is invisible or appears in the wrong place, inspect the geometry before inspecting the renderer. Geographic point coordinates are commonly represented as [longitude, latitude]. A swapped pair may still be numerically valid, so it can avoid a syntax error while placing the feature in another country or outside the current viewport. The same issue affects the center, bounds, and camera methods passed to MapLibre. (maplibre.org)

Use a small FeatureCollection with one known point, one line, and one polygon. Fit the map to the data, then add complexity. For large or frequently changing datasets, avoid sending an unbounded GeoJSON object directly to the browser. MapLibre’s official examples distinguish GeoJSON, vector-tile, clustering, raster, and realtime patterns, which can help you choose a more appropriate transport for the data volume. (maplibre.org)

• •Inspect the first feature’s geometry and properties in the console.
• •Confirm the declared GeoJSON type and coordinate nesting.
• •Check for null, empty, NaN, or nonnumeric coordinates before calling setData.
• •Verify that polygon rings are closed and that the geometry is valid for the intended operation.
• •Use fitBounds or a known camera position to distinguish invisible data from data outside the viewport.
• •Confirm that source and layer IDs used by setData, setLayoutProperty, setPaintProperty, and queryRenderedFeatures actually exist.
• •If the source was produced in another coordinate reference system, transform it before treating its values as longitude and latitude.

Step 4: troubleshoot WebGL, interaction, and deployment

MapLibre GL JS uses WebGL to render interactive maps in the browser. A browser or device may report some level of WebGL support but still fail to create a usable context because of graphics drivers, browser settings, remote-desktop restrictions, resource limits, or security policy. MapLibre’s official examples include a WebGL-support check, so test the target browser and device before treating a rendering failure as a style or data problem. (maplibre.org)

Once the baseline works locally, reproduce the application in its deployed environment. Production-only failures often come from different origins, Content-Security-Policy rules, worker loading, asset paths, HTTPS requirements, caching, or tile endpoints that are unavailable to the deployed domain. A local success is evidence about the local environment, not proof that every production resource is reachable.

• •Test WebGL in the target browser and device class.
• •Inspect worker, glyph, sprite, style, and tile requests separately in the Network panel.
• •Check response status, content type, CORS headers, and cache behavior.
• •Confirm that the deployed Content-Security-Policy permits the scripts, workers, fonts, images, and connections required by the style and data services.
• •Verify HTTPS when dependent resources require a secure context.
• •If the map is inside a hidden tab, modal, or resized panel, call resize after the container becomes visible or changes dimensions.
• •For React or other component frameworks, create and remove the Map instance in the component lifecycle and avoid adding the same source or layer repeatedly.
• •If features are clickable, verify that the event targets the correct layer ID and that the feature is actually rendered at the current zoom.

A repeatable isolation order

When the symptom is simply “nothing appears,” avoid changing several variables at once. Use an isolation order that follows the browser’s dependency chain: container, runtime, style, source, layer, geometry, then application behavior. This prevents a valid data problem from being mistaken for a WebGL problem, or a layer-name mismatch from being mistaken for a failed tile request.

For each stage, record one observable result. For example: the container has 800 pixels of height; the style returns status 200 and valid JSON; the map emits load; one unfiltered circle renders; the point’s coordinates fall inside the camera bounds. Those observations create a small diagnostic record that is more useful than repeatedly changing colors or zoom levels.

• •Container: inspect computed width and height, including hidden ancestors.
• •Runtime: confirm WebGL and check for browser or device-specific errors.
• •Style: fetch and parse the style JSON directly.
• •Source: confirm the source URL, TileJSON, GeoJSON, or inline data response.
• •Layer: confirm the layer type, source ID, source-layer, zoom range, and filters.
• •Geometry: inspect coordinates, geometry type, bounds, and coordinate reference assumptions.
• •Behavior: add events, popups, filters, feature-state, live updates, and framework state one at a time.