Atlaslog
Atlaslog / Field Notes / Loading & display
Field note · Loading & display

KML icons use relative paths and load as broken images

Quick answer

KML resolves a relative href against the URL of the KML file itself, but parsers such as omnivore join it against the page URL. A KML at /data/poi.kml with href images/pin.png requests /cookbook/images/pin.png and returns 404.

Last verified 2026-11-03 · Multiple versions · Cite this page
Applies to: Leaflet 1.9.x · OpenLayers 9.x · Leaflet.omnivore 1.0.0
Symptom
Checklist
  1. Filter the network panel by png and note the full path of the 404.
  2. Compare that path with the KML's own URL to see which base directory was used.
  3. Search the KML for <href> to see whether it is absolute, relative or a file:// URL.
  4. Confirm that <IconStyle> exists at all, since some exporters write no icon.
  5. Re-resolve the href against the KML URL and request the resulting path directly.
Fix

Make href absolute such as /data/images/pin.png, or inline the image as a data URI. When parsing, rewrite with new URL(href, kmlUrl).href inside pointToLayer before building L.icon with iconUrl and iconSize [24, 24].

Code
<Style id="s1">
  <IconStyle>
    <scale>1.0</scale>
    <Icon><href>images/pin.png</href></Icon>
  </IconStyle>
</Style>
<!-- 改成绝对路径(同源) -->
<Icon><href>/data/images/pin.png</href></Icon>

<!-- 或者内联成 data URI,彻底摆脱路径问题 -->
<Icon><href>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQ...</href></Icon>
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). KML icons use relative paths and load as broken images. https://www.jingweizhi.com/en/cookbook/kml-relative-icon.html (accessed 2026-11-03).