Atlaslog / Field Notes / Styling & rendering
Field note · Styling & rendering
A missing sprite key silently drops the whole symbol
Quick answer
Setting `icon-image: 'poi-restaurant'` renders nothing at all and logs no error, while `sprite.json` and `sprite.png` both return 200. The sprite table contains `restaurant`, not `poi-restaurant`, and an unmatched key skips the symbol including its text.
Symptom
- No icon and no label is drawn for the layer even though the source has features
- `'poi-restaurant' in sprite` is `false` after fetching `/sprite.json`
- The sprite keys are `['restaurant', 'hospital', 'parking']`
Checklist
- Fetch `sprite.json` and search for the exact `icon-image` value
- Print `layout['icon-image']` to see whether it is a literal or a `['get', ...]` expression
- Check the distinct property values in the data for case, hyphen and underscore differences
- Confirm the style's `sprite` URL points at the same sprite version
- Diff every icon value in the data against the sprite keys
Fix
Align names with the sprite keys generated by `spritezero sprite ./icons` (the key is the file name without extension), and validate on load with a whitelist: `f.properties.icon = ICONS.has(raw) ? raw : 'marker-default'`.
Code
const sprite = await fetch('/sprite.json').then(r => r.json());
console.log(Object.keys(sprite)); // ['restaurant', 'hospital', 'parking', ...]
console.log(map.getLayer('poi').layout['icon-image']); // 'poi-restaurant'
console.log('poi-restaurant' in sprite); // falsespritezero sprite ./icons
# 生成 sprite.json / sprite.png,键名取自文件名(不含扩展名)
# icons/restaurant.svg -> 键 'restaurant'
Watch out
- Waiting for a console error to catch a bad icon name, since Mapbox GL fails silently on missing sprite keys
- Renaming sprite keys but leaving `icon-image` values with the old prefix, so every POI disappears
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). A missing sprite key silently drops the whole symbol. https://www.jingweizhi.com/en/cookbook/sprite-icon-missing.html (accessed 2026-11-03).