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.
Symptom
- The network panel shows GET /cookbook/images/pin.png 404 and every point renders the browser's broken-image glyph.
- The same KML opens correctly in Google Earth, which resolves against the file location.
- The icon should have been requested from /data/images/pin.png.
Checklist
- Filter the network panel by png and note the full path of the 404.
- Compare that path with the KML's own URL to see which base directory was used.
- Search the KML for <href> to see whether it is absolute, relative or a file:// URL.
- Confirm that <IconStyle> exists at all, since some exporters write no icon.
- 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
- Fixing only the local path: the same relative href breaks as soon as the KML moves to another directory or domain.
- Blindly replacing the icon path while other <href> entries point at legitimate network links.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
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).