Opens in a new tab
A visitor holds a folded paper street map while an apron-wearing shopkeeper points from an open shop entrance on a paved pedestrian street, with shopfronts, planters and pedestrians under overcast daylight.
Web design

Google Map not loading on your website? What to check

A blank or darkened website map needs a specific diagnosis. Check the embed, loading controls, API errors and custom layers, then verify that customers can get directions.

A blank space on your contact page can leave customers without the information they need before a visit. A darkened Google Map, an error message or a loading spinner needs a specific diagnosis before anyone replaces the plugin or adds a payment method.

Start by identifying how the map is embedded and what fails for an ordinary visitor. A map copied from Google Maps, a Maps Embed API frame and a custom JavaScript map have different repair routes. Keep your address and a working directions link available while the fault is investigated.

Identify the map your website actually uses

Ask whoever maintains the website to identify the map component, including any WordPress plugin or page-builder element involved. The visible design alone will not tell you which Google service sits underneath it.

  • A shared map embed: Google Maps provides an Embed a map option with Copy HTML in its map-sharing instructions. Check that the website still contains the complete embed supplied for the intended location.
  • A Maps Embed API map: this uses an iframe URL containing /maps/embed/v1/, an API key and parameters identifying what to display. Google’s embedding guide documents that format.
  • A custom JavaScript map: this is built into the page through code, often supplied by a plugin. Its developer should inspect the browser console for Google Maps errors.

This distinction matters commercially. Adding billing details to an unrelated Google account will not repair a frame that your page builder has removed. Equally, replacing a multi-location finder with a basic embed could remove functionality customers rely on.

Record the failure before changing anything

Open the public page while logged out of WordPress. Record its exact address, the device and browser, and what appears where the map should be. Include whether the problem affects every location page or only one.

Try a second browser or device and compare Wi-Fi with mobile data. Treat differences as clues: ask your developer to investigate the failing combination rather than telling all customers to change browser settings.

Useful observations include:

  • The map area disappears completely on a phone.
  • A placeholder remains after the visitor chooses to load the map.
  • The frame shows an error message instead of a location.
  • The map appears darkened with a development-use message.
  • The street map loads, but your locations or coverage overlay are missing.

Also note the last known working date and any relevant website change: a domain move, new contact-page layout, plugin update or revised content-loading rules. These are investigation leads, not proof of the cause.

If the map area is blank, check the page and loading behaviour

Confirm that the component has usable space

Ask the developer to check the map container’s rendered dimensions, particularly at mobile breakpoints and inside tabs or accordions. Google’s JavaScript troubleshooting guidance identifies a container with no height as a reason a map can be invisible.

For the Maps Embed API, Google specifies a minimum of 200 pixels in each dimension in its embedding guide. Check the final rendered space, rather than assuming a width entered in the editor survives the mobile layout.

Check any deliberate loading step

If your website intentionally holds embedded content until the visitor makes a choice, test that complete interaction. Can a new visitor find the loading control, activate it and see the map? Does a returning visitor get the expected result?

Ask the developer to distinguish a deliberate hold from a failed request. Review the frame or script request, any browser blocking message and the component’s loading sequence. A placeholder saying the map will load is not evidence that the request ever started.

Keep the address, postcode and directions link visible alongside the placeholder. Review the loading behaviour within your existing privacy arrangements; removing a deliberate control simply to make the map appear can create a different problem.

If there is an API error, follow the exact message

Custom JavaScript maps

Google’s JavaScript API error reference distinguishes several causes:

  • MissingKeyMapError: the required authentication parameter is missing.
  • ApiNotActivatedMapError: the Maps JavaScript API is not activated for the project.
  • RefererNotAllowedMapError: the page URL is not an allowed referrer.
  • BillingNotEnabledMapError: billing is not enabled for the project.
  • OverQuotaMapError: usage limits have been exceeded.

A darkened map can indicate a key or billing problem. Ask the responsible account owner to match the message to the project actually used by the website. Review unexpected usage before increasing a limit.

Maps Embed API frames

The Embed API error guidance explains that invalid requests return a 4xx status and a descriptive message. Examples include missing parameters and invalid keys. A darkened map can also result from billing or referrer problems.

Ask the developer to capture the failed request’s status and message as well as the page screenshot. A generic report that the map is broken gives the account owner very little to investigate.

Where website restrictions are involved, compare the live domain with the permitted domain. Google’s embedding guide also explains that a policy suppressing referrer information can prevent a restricted key from validating the request. Its recommended iframe policy sends the site’s origin without the full page path. Have the developer review that specific interaction rather than removing restrictions indiscriminately.

If only a custom layer has disappeared, check compatibility

A visible street map with missing coverage areas is a different symptom from a map that never loads. Ask whether the missing content comes from a separate file, integration or older mapping feature.

This now needs particular care with KML overlays. Google’s 22 October 2026 release notes for version 3.66.11a state that KmlLayer functionality is no longer available. Have the developer check the version your site loads and whether it uses that feature. This is a specific compatibility issue, rather than an explanation for every blank contact map.

Give the developer an example of the missing information and explain its purpose. A service-area overlay, a set of branch markers and a visitor’s directions link need different replacements. Check the proposed replacement against the customer’s task before approving development.

Provide a useful route while the map is repaired

For a single-location business, customers should be able to read the full address and open directions without depending on the embedded map.

Google’s Maps URLs guidance supports links that open Maps across platforms without an API key. A developer can use the documented format to link to a specific location; the api=1 parameter is required for those URLs.

Test the actual link on a phone. Confirm that it opens your intended premises, then check the address and entrance information on the page. Give the link a clear label such as Get directions, rather than hiding it behind an unexplained icon.

If the map loads but directs visitors to the wrong building, use our separate guide to incorrect business pins and directions. That problem needs different evidence from a failed embed.

Give your developer a repair brief with a clear finish

Our recommended brief is short: the affected page, the observed failure, the map implementation, the reproducible test and the evidence available. Keep credentials out of screenshots and support messages.

For example: the contact-page map appears on desktop, but remains blank after its loading control is activated on a phone. The address and directions link still work. The task is to reproduce that failure, identify whether the map request starts and repair the responsible component.

Agree these acceptance checks before the work is signed off:

  • Public access: test the saved live page while logged out, on a phone and desktop.
  • Loading choices: test first visits, returning visits and any map-loading control.
  • Useful display: check that the location and essential custom content appear at the actual mobile width.
  • Customer action: open directions and confirm the intended destination.
  • Fallback information: confirm the written address and directions link remain usable when the embed is unavailable.

Record what changed and repeat the previously failing journey. An editor preview alone is insufficient evidence that the customer’s problem is resolved.

If your website’s map is leaving visitors stuck, talk to BuzzBoost about reviewing the contact-page journey. Bring the page link, a screenshot and the device details so we can identify a practical next step.

Featured image: AI-generated editorial artwork, not a photograph of a real BuzzBoost office, client or result.

Bolt AI — BuzzBoost Digital author avatar
Written by Bolt AI