Diagnosing Mapbox GL JS Style Loading Failures: CORS, Tokens, and Resource Paths

Recognizable Condition

Your Mapbox GL JS map renders as a blank container, yet the page loads without a JavaScript crash. The browser console shows messages such as Cross-origin request blocked, Access-Control-Allow-Origin header missing, or Failed to load style JSON with a 401 status. Tiles may appear for a moment and then disappear, or the map may never paint at all. These symptoms usually mean the browser refused a resource because the server did not return the expected CORS headers, or because the style URL carried an invalid or missing access token.

Cause and Diagnostic Table

Console Error or Symptom	Likely Cause	First Diagnostic
Cross-origin request blocked on a tile request	Custom tile server is not sending Access-Control-Allow-Origin	Inspect the failing tile request in the Network tab; check response headers
Access-Control-Allow-Origin header missing	Sprite, glyph, or custom vector source misconfigured for cross-origin reads	Filter Network tab for sprite, glyph, or custom source URLs
Failed to load style JSON with 401	Missing, expired, or insufficiently scoped Mapbox access token	Copy the style URL and request it with curl -I
Failed to load sprite image or 404 on sprite	Incorrect sprite path in the style JSON, or the sprite host blocks the origin	Open the sprite URL directly in a browser tab

Ordered Checks

1. Confirm the style URL and token. Ensure the style URL passed to mapboxgl.Map includes a valid access_token query parameter and points to a public style or a style your token can read.
2. Reproduce and inspect the Network tab. Open browser developer tools, reload the map, and filter for style, tile, sprite, and glyph requests. Note any non-200 status codes.
3. Check response headers. For each blocked request, look at the response headers. A successful cross-origin resource should include Access-Control-Allow-Origin matching your page origin or *.
4. Test outside the browser. Run a command like this in your terminal, replacing the URL with your style or tile endpoint:

   curl -I "https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

   Look for a 200 status and an access-control-allow-origin header in the response.
5. Validate custom endpoints. If you serve tiles, sprites, or glyphs from your own domain, confirm the server configuration includes the CORS header for the requesting origin.
6. Verify token status. Check the Mapbox access token in your account dashboard to confirm it is active and has the required scopes for the styles and tiles you are loading.

Fixes Tied to Findings

Missing CORS Header on a Custom Tile Server

If the Network tab shows a blocked tile request and the response lacks Access-Control-Allow-Origin, add the header on your tile server. For an nginx reverse proxy in front of a tile backend, a location block might look like this:

location /tiles/ {
    add_header Access-Control-Allow-Origin "https://your-app-domain.com";
}

Replace https://your-app-domain.com with the exact origin serving your Mapbox GL JS application. A wildcard (*) is acceptable for public data, but it allows any website to read the resource; restrict the origin in production.

Invalid or Missing Access Token

If the style request returns 401, the token is absent, expired, or lacks scopes. Regenerate the token in the Mapbox dashboard and update every place it appears: the style URL, any direct tile URLs, and the accessToken option if you set it globally. A minimal initialization looks like this:

mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12'
});

If you use a custom style hosted outside Mapbox, append the token to the URL: https://api.mapbox.com/styles/v1/username/style-id?access_token=YOUR_MAPBOX_ACCESS_TOKEN.

Sprite or Glyph URL Failures

When the console reports a sprite or glyph failure, open the exact URL from the style JSON in a new browser tab. If it returns 404, the path in the style is wrong; correct the sprite and glyphs properties to valid Mapbox CDN paths. If it returns 200 in the tab but fails in the app, the host is likely blocking your origin; add the CORS header on that host or switch to the Mapbox-hosted equivalents.

Escalation Criteria

Escalate to Mapbox support only after the ordered checks pass and the map still fails to render. Before opening a ticket, reduce the problem to a minimal reproducible example: a single HTML file that loads Mapbox GL JS, sets the access token, and attempts to display the failing style. Capture the full console output and a HAR file or screenshot of the Network tab showing the failing requests, their status codes, and response headers. Include the style ID, the approximate timestamp, and the browser version. Do not include secret tokens in public trackers; share them only through Mapbox's secure support channel.

Limitations and Verification

These diagnostics assume Mapbox GL JS v2 or v3 and a standard browser environment. Browser extensions, corporate proxies, and strict Content Security Policy rules can produce similar console errors even when the server headers are correct; test in an incognito window with extensions disabled to rule out local interference. Mapbox may update CORS or token requirements for custom domains, so treat server configurations as versioned infrastructure that needs periodic review.

To verify a fix, reload the map with the Network tab open and confirm that style, tile, sprite, and glyph requests all return 200 and include the expected Access-Control-Allow-Origin header. The map should paint tiles without further console errors. If a tile server change was required, also confirm the header appears for both GET and HEAD requests, since some browsers and caching layers probe differently.