Atlaslog
Atlaslog / Field Notes / MapLibre styles & layers
Field note · MapLibre styles & layers

Style fails to load and the map stays a grey background

Quick answer

The canvas appears and pans, but only a flat grey background renders because style.json never loaded and isStyleLoaded() stays false. Every addLayer call then throws because the style is not ready.

Last verified 2026-11-03 · Multiple versions · Cite this page
Applies to: MapLibre GL JS
Symptom
Checklist
  1. Register map.on('error') to surface errors MapLibre otherwise swallows.
  2. Fetch the style URL and print status, content-type and the parsed sprite and glyphs fields.
  3. Check the network panel for 404, a CORS block or net::ERR_CERT_AUTHORITY_INVALID.
  4. Validate that the JSON parses, not just that it returns 200.
Fix

Serve style.json same-origin with absolute sprite and glyphs paths, keep a minimal inline background-only fallback style, then map.setStyle() after the fetch resolves, and add sources and layers inside map.on('load').

Code
Error: Could not load style: https://styles.example.cn/basic/style.json
    at Style.load (style.ts:673)
Uncaught Error: style is not done loading
map.on('error', function (e) {
  console.error('地图错误', e.error && e.error.message, e.sourceId, e.tile);
});
Watch out
All 120 field notesChinese originalRunnable examples
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Cite this page

Atlaslog (2026). Style fails to load and the map stays a grey background. https://www.jingweizhi.com/en/cookbook/maplibre-style-load-fail.html (accessed 2026-11-03).