Satellite Maps Not Showing in BlenderGIS? Fix It in Minutes
A blank viewport where satellite imagery should be is one of the most common BlenderGIS problems — and it is almost always one of six things. Work through this checklist from most likely to least likely and you will usually have imagery back within minutes.
The 6-Step BlenderGIS Basemap Checklist (Most Likely First)
BlenderGIS does not host satellite imagery itself: when you load a basemap, the addon requests image tiles from a web map provider (such as MapTiler) and draws them in your 3D viewport. The steps below follow that chain from the most frequent break to the least frequent.
Step 1 — Check the CRS: Use Web Mercator (EPSG:3857)
Web map tile services publish their imagery in Web Mercator (EPSG:3857). If your scene or basemap request uses a different coordinate reference system, the tiles either come back blank or land misaligned. A wrong CRS is the single most common cause of a basemap that “loads” but shows nothing.
How to fix: when you start a basemap in BlenderGIS, confirm the coordinate system for the map request is Web Mercator / EPSG:3857. If you changed the scene CRS (for example while importing terrain), set the basemap layer back to EPSG:3857 and reload — or re-run the import with 3857 selected from the start.
Step 2 — Enter Your MapTiler API Key
Tile providers like MapTiler require a (free) API key before they serve imagery. BlenderGIS has no tiles of its own, so a missing or invalid key means an empty viewport — sometimes with an HTTP Error 403: Forbidden in the console.
How to fix: get a free key from your tile provider, then go to Edit > Preferences > Add-ons > BlenderGIS > Basemaps, paste it in the key field, save, and reload the basemap. For the full walkthrough, see our BlenderGIS API key setup guide.
Step 3 — Clear the Cache Folder
BlenderGIS stores downloaded tiles in a local cache folder so it does not re-download them every time. That folder must exist, be persistent, and be writable by Blender. After a crash or an interrupted download, cached files can become corrupted — a classic cause of tile failures that survive restarts.
How to fix: open Addon Preferences, note the cache folder path, and confirm it is a normal local folder you can write to (not read-only, not a cloud-synced folder). Then close Blender, delete the folder’s contents, restart, and reload the basemap — BlenderGIS simply re-downloads the tiles.
Step 4 — Check Internet Connection and Firewall
Basemaps need a live connection to the tile servers. Office and school networks, strict firewalls, proxies, and some VPNs can block tile URLs while normal browsing still works — confusing, because everything else on your computer is online.
How to fix: first open the tile provider’s website in your browser to verify it is reachable. Then check that your firewall allows Blender outbound connections (add an exception if needed), and if you are on a managed network, try a phone hotspot to confirm the network is the blocker.
Step 5 — Check Zoom Level and Tile Coverage
Not every zoom level has imagery for every location. If you are zoomed beyond the provider’s maximum zoom for that area, or your area sits outside their coverage, the viewport stays empty. Mistyped or swapped coordinates produce the same symptom.
How to fix: zoom out a few levels and reload the basemap. Double-check your coordinates — latitude and longitude are easy to swap, and a misplaced minus sign can put your area of interest in the ocean. Confirm the location in a web map first, then re-run the import with the verified coordinates.
Step 6 — Update BlenderGIS (and Check Your Blender Version)
Tile servers and web APIs change over time, and old addon versions stop working against them. If you are on Blender 4.2 or newer, you need BlenderGIS v2.2.12 or newer; the latest stable release is v2.2.15 (December 20, 2025). macOS users should be on at least v2.2.10, which fixed the ImageIO-related tile decoding issue that produced struct.error: unpack requires a buffer of 4 bytes. The minimum supported Blender version is v2.83 LTS.
How to fix: download the latest release from the BlenderGIS download page and update the addon (remove the old copy first so you never have two versions installed at once), then restart Blender and retry the basemap.
When the Checklist Isn’t Enough
If the viewport is still blank, check Blender’s console or status bar for the exact error text — the wording tells you where the chain is breaking:
- HTTP Error 403: Forbidden — the tile server rejected the request — almost always a missing, expired, or mistyped API key. Re-enter it carefully with no extra spaces.
- struct.error: unpack requires a buffer of 4 bytes (macOS) — a tile decoding problem fixed in BlenderGIS v2.2.10 and newer. Update the addon and clear the cache folder.
- Tiles load but look wrong or misaligned — you are almost certainly not on EPSG:3857 for the basemap layer. Go back to Step 1.
- Nothing happens at all, no error — re-check the cache folder (Step 3) and the firewall (Step 4).
For other errors — failed OSM imports, install failures, a missing GIS menu — head to the BlenderGIS troubleshooting hub.
Related Guides
- BlenderGIS API Key Setup — get and enter your MapTiler and OpenTopography keys.
- Fix the Overpass 406 Error — when OSM vector imports fail instead of basemaps.
- Download BlenderGIS — grab the latest stable release (v2.2.15).
- Troubleshooting Hub — every common BlenderGIS error in one place.
Frequently Asked Questions
Why is my BlenderGIS basemap blank even though I entered an API key?
The next most likely culprits are a wrong CRS (the basemap must be requested in Web Mercator / EPSG:3857) and a corrupted or unwritable cache folder. Check the CRS first, then clear the cache, then verify the key was pasted without extra spaces.
Where do I enter the MapTiler API key in BlenderGIS?
Go to Edit > Preferences > Add-ons, find BlenderGIS, open its preferences, and look for the Basemaps section. Paste the key there and save your preferences. Our API key setup guide walks through it step by step.
Is it safe to delete the BlenderGIS cache folder contents?
Yes. The cache only holds downloaded tiles and elevation files. Deleting its contents forces BlenderGIS to re-download what it needs, which is exactly why clearing it fixes corruption-related failures. Just make sure the folder itself still exists and Blender can write to it.
Which BlenderGIS version do I need for Blender 4.2 or newer?
You need BlenderGIS v2.2.12 or newer on Blender 4.2+ (latest stable: v2.2.15, December 20, 2025). An older addon on a new Blender is a common reason basemaps break after a Blender upgrade.
Why does the basemap work in one location but not another?
Tile coverage varies by location and zoom level. Some regions have no imagery at very high zoom levels. Zoom out a few levels and retry, and double-check that your coordinates are correct and not swapped.
Do I need an internet connection for BlenderGIS basemaps?
Yes. Basemaps are streamed from web tile servers at import time; there is no offline imagery bundled with the addon. Firewalls, proxies, and managed networks that block the tile servers will leave the viewport blank.