WordPress Google Map Not Showing? Read the Error First

The contact page has a map so customers can find the shop. Today it is a grey rectangle. Or a darkened map with “For development purposes only” stamped across it in a repeating pattern. Or a pop-up line saying “This page can’t load Google Maps correctly”, with a question asking whether you own the website.

A Google map not showing in WordPress is one of the more readable problems a site can have, because Google tells you a lot if you know where to look. The first thing to establish is which of two quite different methods put the map on your page, because one of them almost never breaks and the other has several settings outside WordPress that can.

WordPress Google map not showing? Check how it was added

Open the page in the editor and click the map. If you see a block containing <iframe src="https://www.google.com/maps/embed?..., it is a simple embed. If you see a widget or plugin with a field for an “API key”, it is the JavaScript API.

If the map uses an API key: read the error first

With the broken page in front of you, bring up the browser’s developer tools (F12 on most Windows browsers) and switch to the Console tab, then refresh. If those tools are unfamiliar, our guide on buttons that do not respond to clicks walks through them. Google Maps writes a named error to the console when it refuses to load. The name tells you the cause directly.

“For development purposes only” or BillingNotEnabledMapError

The Maps JavaScript API requires the Google Cloud project that owns the key to have a billing account attached. Without one, the map either does not load or loads darkened with that watermark. This often appears on older sites where a key was created years ago under different rules, or where the card on the billing account expired. Sign in to the Google Cloud console with the account that owns the project and check the billing account linked to it. Costs depend on usage and Google’s current rates; the Google Maps Platform pricing page lists them, and Google’s usage reports in the console show what your site actually uses.

ApiNotActivatedMapError

Keys belong to a project, and each Google Maps service has to be switched on in that project separately. If the Maps JavaScript API is not enabled, the key is refused. In the Cloud console, open the project’s APIs and services library and enable the Maps JavaScript API. Some map plugins also use the Geocoding or Places API to turn an address into a pin; if the map loads but the marker is missing, check those too.

RefererNotAllowedMapError

A well-set-up key is restricted to your website’s address, so nobody else can copy it and run up usage on your account. If the restriction does not match the address the site is actually using, Google refuses it. This often follows:

• moving the site to a new domain;
• switching between www and non-www;
• moving from a staging address to the live one.

In the key’s settings, the website restrictions should cover the real address, for example example.com/* and *.example.com/*, with your own domain in place of example.com. Change the restriction, save, and allow a few minutes before testing again.

InvalidKeyMapError or MissingKeyMapError

The key in the plugin’s settings is wrong, was deleted in the Cloud console, or was never entered. A theme update or a switch to a different map plugin can leave the key field empty. Copy the key again from the console into the plugin’s settings.

Google documents each of these error names in its Maps JavaScript API documentation at developers.google.com/maps, along with how keys and restrictions work.

Map embed blank with no error at all

No console message, no grey “can’t load” text, just nothing. These are the usual reasons, and they apply to simple embeds as well as API maps.

The map’s container has no height

A map fills whatever box it is placed in. If that box has no height set, the map is technically there but zero pixels tall. This happens when a page builder section is set to “auto” height, or when custom CSS was removed. Inspect the empty area: if the highlighted element is very thin, give the map widget or iframe a fixed height in its settings.

A cookie consent tool is blocking Google

Consent plugins commonly hold back Google Maps until the visitor agrees to third-party or marketing cookies, because loading the map sends the visitor’s details to Google. Visitors who have not accepted see a blank or a placeholder. Test in a private window and accept cookies; if the map then appears, the tool is doing what it was configured to do. Most consent tools can show a “Load map” placeholder instead of an empty gap. Our guide on videos blocked from playing deals with the same consent issue for YouTube.

The map is inside a tab, accordion or popup

A map that loads inside a hidden area can draw itself at the wrong size, because when it loaded, its box was hidden and had no measurable width. When the tab opens, you see grey tiles or a tiny map in one corner. Moving the map out of the hidden section, or using a map plugin that redraws when the tab opens, fixes it.

The embed code was pasted somewhere that strips it

Iframe code pasted into a normal paragraph is shown as text or removed. It needs a Custom HTML block or an HTML widget. WordPress also strips iframes from content saved by accounts that are not allowed to post unfiltered HTML, such as authors and contributors. If someone with a lower role pasted it, try it from an administrator account.

A cached page from before the change

If you fixed the key or the code and the visitor view has not changed, the page may simply be cached. See the guide on fixes that do not appear on the live page for where to clear it.

The embed works but looks wrong

A simple embed can load perfectly and still be a problem. Two complaints come up often.

It spills off the screen on phones. The embed code Google gives you includes a fixed width and height, such as width="600". On a narrow phone screen that fixed width can push past the edge of the page and make the whole layout scroll sideways. Change the width in the code to 100%, or place the map in a page builder widget that sizes it for each screen.

It shows the wrong pin or a vague area. The embed shows whatever you were looking at when you copied the code. If you searched for a street rather than your business, the map shows the street. Search for your business by name in Google Maps, open its own listing, and copy the embed code from there, so the pin carries your business name.

Do you need the API map at all?

For a single business location on a contact page, a simple embed from Google Maps does the job with no key, no billing account and nothing to expire. If your site uses an API key only to show one pin, switching to an embed removes most of the causes above. The API is worth it when you need several locations, a custom colour scheme, a store locator, or directions built into the page.

It is also worth checking that your map points at the right listing. If customers search for you by name, your Google Business Profile is what they will see in Maps, so the embed and the profile should show the same address.

What to have ready if you hand it over

• The page address with the broken map.
• The exact text of the console error, if one appears.
• Which plugin, theme option or widget shows the map.
• Who owns the Google account the API key was created under. If nobody knows, that is worth finding out regardless.

That last point is often the real blocker. A key created by a former developer under their own Google account cannot be fixed without access to it, and creating a fresh key under the business’s own account is usually the better long-term move. If you would rather someone else sorted out the key, the account and the settings, our professional wordpress bug fixing page explains how we work.

A blank map usually comes down to one named error in the console, and that name already tells you which setting to open.

Next in this series: WordPress Popup Not Closing or Keeps Showing? Fix It