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.
Symptom
- 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 on every addLayer call.
- map.isStyleLoaded() stays false while the background shows the #f2f4f6 default fill.
Checklist
- Register map.on('error') to surface errors MapLibre otherwise swallows.
- Fetch the style URL and print status, content-type and the parsed sprite and glyphs fields.
- Check the network panel for 404, a CORS block or net::ERR_CERT_AUTHORITY_INVALID.
- 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 loadingmap.on('error', function (e) {
console.error('地图错误', e.error && e.error.message, e.sourceId, e.tile);
});
Watch out
- Calling addLayer right after the Map constructor throws and leaves an empty style that never recovers without setStyle.
- Writing sprite and glyphs as relative paths makes them resolve against the style.json directory and 404.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
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).