Atlaslog / Field Notes / MapLibre styles & layers
Field note · MapLibre styles & layers
Sprite 404s turn every POI icon into a blank square
Quick answer
The style's sprite field is a prefix that MapLibre expands into up to four files, and all of them 404, so road shields and station icons render as empty boxes while the rest of the map is fine.
Symptom
- GET /sprites/sprite.json 404, /sprites/sprite.png 404 and /sprites/sprite@2x.json 404 together.
- Error: Could not load sprite at /sprites/sprite.json.
- Highway numbers and airport symbols become placeholder squares while roads and water render normally.
Checklist
- Print map.getStyle().sprite to see the configured prefix.
- Fetch all four derived URLs and check their status codes.
- Open sprite.json and confirm each icon has x, y, width, height and pixelRatio.
- Check whether a relative sprite path resolves under /styles/basic/.
Fix
Set sprite to the prefix only, for example /sprites/sprite, generate all four files with spritezero (--ratio 2 for @2x), or add an Nginx fallback rewriting sprite@2x.* to the 1x files.
Code
GET /sprites/sprite.json 404 (Not Found)
GET /sprites/sprite.png 404 (Not Found)
GET /sprites/sprite@2x.json 404 (Not Found)Error: Could not load sprite at /sprites/sprite.jsonWatch out
- Writing /sprites/sprite.json in the style makes MapLibre request sprite.json.json.
- Shipping only sprite.json and sprite.png breaks on 2x devices, which request the @2x pair.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Sprite 404s turn every POI icon into a blank square. https://www.jingweizhi.com/en/cookbook/maplibre-sprite-missing.html (accessed 2026-11-03).