Atlaslog / Field Notes / Loading & display
Field note · Loading & display
Tiles return 404 or are blocked by CORS
Quick answer
The basemap shows grey squares because requests fail: 404 from a bad URL template or a swapped y-axis, 403 from an invalid key or referer, or CORS when crossOrigin is enabled for canvas export.
Symptom
- The network panel is full of red 404s and the grid stays grey while the map framework itself loads fine.
- A 200 response whose body is an HTML login page renders as a broken image.
- Console reports a CORS error only after crossOrigin is set for canvas export.
Checklist
- Read the status code first and classify 404, 403 or CORS.
- Open one tile URL directly in the browser to test whether the address itself is valid.
- For 404, check {z}/{x}/{y} order (some services use {z}/{y}/{x}) and the y-axis flip ({-y} in Leaflet, a custom tileUrlFunction in OpenLayers).
- For 403, check the key, the domain whitelist (localhost and file:// are often rejected), the daily quota and the HTTPS requirement.
- For CORS, confirm whether crossOrigin is only needed for toDataURL export and remove it otherwise.
Fix
Correct the URL template and y-flip, whitelist the domain or renew the key, and enable crossOrigin only when the canvas must be exported. Add a tileerror handler so failures surface to users instead of leaving grey blocks.
Code
'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
'{z}/{x}/{-y}.png'L.tileLayer(url, {
crossOrigin: 'anonymous'
}).addTo(map);
Watch out
- Blaming the map library for a 404 caused by a swapped {x}/{y} order.
- Enabling crossOrigin on every tile layer 'for safety', which converts a working basemap into a CORS failure.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Tiles return 404 or are blocked by CORS. https://www.jingweizhi.com/en/cookbook/tile-404-cors.html (accessed 2026-11-03).