Rebuilding a Kapadokya Route Cache After a Bad Tile Server

Last March I was planning a week between Göreme and Derinkuyu with almost no signal, so I pre-downloaded map tiles for the whole route onto an old Android phone. I used a small self-hosted tile proxy, not an official app. The cached set was about 4.2 GB across zoom levels 10–16. Two days before leaving, the tile server I was pulling from started returning 200 responses with blank gray PNGs, and I only noticed because the tiles on the phone looked uniformly pale. The cache was poisoned: roughly 60% of z15/z16 tiles were empty but present, so my offline app treated them as valid and never refetched.

My fix was to stop trusting HTTP status and start checking pixel content. I wrote a tiny Python pass over the cache directory:

from PIL import Image
import os, hashlib

BAD = 0
for root, _, files in os.walk("tiles"):
    for f in files:
        p = os.path.join(root, f)
        try:
            im = Image.open(p).convert("RGB")
        except Exception:
            os.remove(p); BAD += 1; continue
        colors = im.getcolors(maxcolors=8)
        if colors and len(colors) == 1:
            os.remove(p); BAD += 1
print("removed", BAD)

Single-color tiles are almost always placeholders, so deleting them forces a refetch. I also switched the proxy to hash the response body and compare against a known-good checksum for a random 1% sample before writing. That cost me maybe 15 minutes per 500 MB, which is fine on a home connection but painful on a phone hotspot.

Why it works: the app’s cache key is the URL, not the content, so an empty tile at the right URL is indistinguishable from a real one. Deleting the file is the only reliable invalidation. The tradeoff is that you lose tiles you might actually need if the server is down when you refetch, so I kept a separate tiles.bak copy before running the cleaner and only pruned z15+.

Where this breaks: single-color tiles are legitimate over open water or large plains, and I deleted a few real ones around Tuz Gölü. Also, some servers serve valid tiles with a 404 body that PIL happily opens, so the exception branch never fires. I caught that only after staring at gray squares on the bus. If your client uses a SQLite mbtiles file instead of loose files, this script does nothing and you need to rebuild the archive.

What do you use to verify offline tiles are actually real before you leave coverage?