Atlaslog / Field Notes / Tiles
Field note · Tiles
Tiles return 204 instead of 404, leaving invisible white gaps
Quick answer
The tile service answers `204 No Content` outside its data extent, which the browser treats as a successful load. The area renders as transparent white with no grey block and no `tileerror`, so monitoring reports everything healthy.
Symptom
- The network panel shows a run of `204 No Content` responses for tiles outside coverage
- `tileerror` never fires and the basemap failure notice never appears
- `e.tile.naturalWidth` is 0 in the `tileload` handler for those tiles
Checklist
- Filter the network panel by status 204, or by 200 responses with a 0-byte body
- Inspect `Content-Type` and `Content-Length` on the tile response
- Log `e.tile.naturalWidth` inside `tileload` to catch zero-size images
- Check the tile server's documented empty-tile policy: 204, transparent PNG, or 404
- Reproduce with a coordinate well outside coverage
Fix
Make the server return 404 for missing tiles (`try_files $uri =404`) so the client can react, or return a 1x1 transparent PNG; on the client, count `tileload` events with `naturalWidth === 0` and show a no-data hint after a few.
Code
layer.on('tileload', e => {
if (e.tile.naturalWidth === 0) console.warn('空瓦片', e.coords, e.tile.src);
});
// 204 的瓦片会打出警告,而 tileerror 不会触发# Nginx:空目录不再返回 204,而是 404
location /tiles/ {
try_files $uri =404;
}
# 若希望缺图时不破坏画面,返回 1×1 透明 PNG
location /tiles/ {
try_files $uri /blank.png;
add_header Cache-Control "public, max-age=86400";
}
Watch out
- Monitoring only `tileerror` counts and concluding the layer is fine, because 204 is a 2xx success
- Replacing 204 with a 200 HTML error page, which some browsers report as an error event and others render as a broken image
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Tiles return 204 instead of 404, leaving invisible white gaps. https://www.jingweizhi.com/en/cookbook/tile-204-blank.html (accessed 2026-11-03).