Home Assistant map: API KEY REQUIRED error fix

Home Assistant map says API KEY REQUIRED: the real fix

Suddenly, our Home Assistant map dashboard and map cards started showing tiles with the frustrating message: API KEY REQUIRED. This happened in October 2026, and it meant we couldn’t see our device locations or zones on the map anymore. It was a real head-scratcher, especially since we hadn’t changed anything in our setup.

If you’ve encountered this exact problem, you’re in the right place. We’ll walk you through what caused this issue in our Home Assistant setup, what we tried, and the straightforward solution that got our maps working perfectly again. We’ll also share a crucial mistake we made along the way so you can avoid it.

This post is for anyone using Home Assistant, especially if you’re a beginner. We’ll explain any technical terms as we go, so you can follow along easily.

What you need

• An existing Home Assistant setup
• Basic access to your Home Assistant interface to check versions and perform updates

The mystery of the missing map tiles

The first thing we noticed was that all our map-related views, including the main map dashboard and any custom map cards we had created, were affected. Instead of showing streets and terrain, they displayed gray squares with “API KEY REQUIRED” written on them. It was a clear sign that something was blocking the map data from loading.

Checking our Home Assistant version

Since we hadn’t changed anything ourselves, our first thought was to check if Home Assistant itself had updated automatically or if there was a known issue. Knowing your Home Assistant version is always a good first step when troubleshooting. Here’s how to check it:

1. In your Home Assistant interface, go to Settings.
2. Click on About.
3. Look for the “Home Assistant Core” version.

We noted down our version, which at the time was older than what we eventually needed.

The root cause: CARTO and API keys

After some digging, we discovered the underlying reason for the “API KEY REQUIRED” message. Home Assistant used to rely on a service called CARTO for its default basemap tiles. Basemap tiles are the background images that show roads, buildings, and land on a map.

It turned out that CARTO started requiring an API key in August 2026. An API key is like a secret password that programs use to identify themselves and get permission to use a service. Since our Home Assistant version wasn’t set up to provide this key to CARTO, the map tiles simply stopped loading.

Crucially, we learned that older versions of Home Assistant did not have a configuration option to add this API key. This meant we couldn’t just tweak a setting to fix it.

The real fix: update Home Assistant

The good news is that the Home Assistant developers were aware of this change and had already implemented a solution. Starting with Home Assistant version 2026.9, the system switched away from CARTO. Instead, it now uses OpenStreetMap-based vector tiles served directly through Home Assistant’s own proxy endpoint. A proxy endpoint is like a middleman that handles requests, in this case, for map tiles, making sure they load correctly without needing external API keys.

This meant the fix for us was straightforward: we needed to update our Home Assistant to version 2026.9 or newer.

Before you update: critical checks

Before you start any major update, it’s always wise to take a couple of precautions. We learned this the hard way!

1. Check free disk space: Updates can take up a surprising amount of space. Make sure your Home Assistant installation has enough room. If your disk is full, the update can fail, leaving you with an unresponsive system. We’ll cover our experience with this in the ‘What went wrong’ section.

2. Create a backup: This is perhaps the most important step. A backup is a copy of all your Home Assistant data and settings. If anything goes wrong during the update, you can restore your system to its previous working state. Home Assistant offers built-in backup options, which you can usually find under Settings > System > Backups.

How to update Home Assistant safely

Once you’ve checked your disk space and created a backup, you’re ready to update. The exact steps might vary slightly depending on how you installed Home Assistant (e.g., Home Assistant OS, Container, Supervised), but generally, you can update through the user interface:

1. In Home Assistant, go to Settings.
2. Click on System.
3. Go to Updates.
4. If an update is available, you will see an option to install it. Make sure the version offered is 2026.9 or newer.
5. Follow the on-screen prompts to complete the update. Your Home Assistant might restart during this process.

Verifying the fix

After the update was complete and Home Assistant had restarted, we eagerly checked our map dashboard. Success! The map tiles were back, showing our home layout and device locations just as they should. The “API KEY REQUIRED” message was gone.

What if custom map cards still show old tiles?

In some cases, especially with custom map cards you’ve added to your dashboards, you might find they still show the old, broken tiles even after updating Home Assistant. This is usually due to your browser’s cache. A cache is like a temporary storage area for frequently accessed data, making things load faster. Your browser might be holding onto the old, broken map data.

To fix this, you need to perform a hard refresh or clear your browser’s frontend cache:

• Hard Refresh: This forces your browser to download all content again, ignoring its cache. On most browsers, you can do this by pressing Ctrl + Shift + R (Windows/Linux) or Cmd + Shift + R (Mac).

• Clear Frontend Cache: In Home Assistant, you can also clear the frontend cache directly. Go to your Home Assistant profile (click on your user icon in the sidebar), scroll down, and look for an option to “Clear frontend cache.”

After a hard refresh or clearing the cache, your custom map cards should also display correctly.

What went wrong / gotchas

Our update process wasn’t entirely smooth. We initially tried to update without checking our free disk space. The update failed with an HTTP 500 error, which is a generic message indicating a server problem. After some investigation, we realized that the disk where our Home Assistant setup was installed was completely full. There wasn’t enough room for the update files to be downloaded and installed.

We had to free up space before attempting the update again. This experience really highlighted the importance of those pre-update checks, especially ensuring you have enough free disk space. Always check before you start!

Seeing “API KEY REQUIRED” on your Home Assistant maps can be alarming, but as we found, the solution is relatively simple: update your Home Assistant to version 2026.9 or newer. Remember to always back up your system and check your disk space before starting any major update. With these steps, you’ll have your maps working perfectly again in no time, giving you a complete overview of your smart home.

FAQ

Why did my Home Assistant map suddenly stop working?

Your Home Assistant map likely stopped working because the service it used for map tiles, CARTO, started requiring an API key in August 2026. Older Home Assistant versions didn’t have a way to provide this key, causing the map tiles to display “API KEY REQUIRED” instead of the actual map.

What Home Assistant version fixes the map API key issue?

The issue is fixed in Home Assistant version 2026.9 and newer. These versions switched to using OpenStreetMap-based vector tiles, which are served through Home Assistant’s own proxy endpoint and do not require an external API key.

My custom map cards still show “API KEY REQUIRED” after updating, what should I do?

If your custom map cards still show the old error after updating, it’s likely due to your web browser’s cache. Try performing a hard refresh of your browser (Ctrl + Shift + R or Cmd + Shift + R) or clear your Home Assistant frontend cache from your user profile settings.