Atlaslog
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.

Last verified 2026-11-03 · Multiple versions · Cite this page
Applies to: Mapbox GL JS 2.15 / 3.x / MapLibre 4.x / spritezero-cli 1.3
Symptom
Checklist
  1. Fetch `sprite.json` and search for the exact `icon-image` value
  2. Print `layout['icon-image']` to see whether it is a literal or a `['get', ...]` expression
  3. Check the distinct property values in the data for case, hyphen and underscore differences
  4. Confirm the style's `sprite` URL points at the same sprite version
  5. 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);                   // false
spritezero sprite ./icons
# 生成 sprite.json / sprite.png,键名取自文件名(不含扩展名)
# icons/restaurant.svg  ->  键 'restaurant'
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). A missing sprite key silently drops the whole symbol. https://www.jingweizhi.com/en/cookbook/sprite-icon-missing.html (accessed 2026-11-03).