My map is showing up blank or gray

If your Stockist map is using Mapbox as your map provider, and the map on your website is showing a blank/gray background instead of the regular map imagery, this usually indicates an issue with your site’s Mapbox key.

Overview

This article applies if you’re seeing a grey map background appearing instead of the usual map imagery. You may still see the store pins on the map, but the imagery of land/water/roads doesn’t appear behind them:

You may also notice that searching the map for a city or postcode shows an error message.

Possible causes

This problem generally indicates that there’s an issue with the Mapbox key for your site. This key would have been created directly with Mapbox and added to your Stockist account when originally setting up your map.
Your Mapbox key powers the imagery that appears behind the map pins, so if there’s an issue with your key, this will prevent the map imagery from showing up on your website.
There are a couple of specific problems that can cause this issue:

1. Incorrect key restrictions

As part of setting up your Mapbox key, you can choose a specific list of websites that can use the key. This prevents other websites from copying your key and incurring usage on your account.
If you've just created your Mapbox key or recently changed your site’s web address, it’s possible that the list of allowed sites for your key is incorrect.
To confirm if this is the issue, you can follow the steps in our article on setting up URL restrictions for your Mapbox key.
If Stockist was set up to use the "Default public token" from Mapbox, or if you confirmed that the URLs of your key match your website, the problem may be caused by another issue below.

2. Mapbox's free tier exceeded

Your Mapbox key includes a monthly free usage tier that's enough for around ~10,000 map views every month with no additional cost beyond your regular Stockist subscription.
Beyond the free tier, Mapbox provides additional usage of their map services on a pay-as-you-go basis. If your store locator has high traffic in a particular month and exceeds the free tier, Mapbox will issue an invoice for any additional usage above and beyond the free amount. We have a separate article with details on how Mapbox's free tier works and how any overage is calculated.
If a Mapbox invoice was issued for your account but couldn't be paid (e.g. due to a payment issue or because your Mapbox account doesn't have a credit card attached), Mapbox will temporarily disable your map key. This causes the map imagery to stop appearing on your site until the issue is resolved.
To check for this, the steps are:
  1. Log into your Mapbox account at https://account.mapbox.com/
  2. Click Invoices in the left menu:

  3. Check the list of invoices for any that are unpaid. If you see any, you can click on them to see more details. Resolving any outstanding invoices should automatically reactivate your key within 15-20 minutes.

I’m not sure what my Mapbox account email is

If you created your Mapbox account a while ago and aren’t sure what email address you used, you may not be able to log into the Mapbox dashboard.
For privacy reasons, Mapbox doesn’t make it possible to identify your account's email address based on your map key. Unfortunately, this means that our support team doesn't have any way to identify your Mapbox account email.
You can try the following options to identify your account email:
  1. Mapbox sends a welcome email when signing up, and an additional notification if your account ever exceeds the free tier. You could check the inboxes (and spam folders) of any likely email accounts for any messages from Mapbox. If you find one, that’s likely the address that can be used to log into Mapbox.
  2. In certain cases, Mapbox’s support team may be able to assist with recovering access to your account. They have the steps here to start this process, although please note that it may take a couple of days to hear back.
  3. If you're not able to regain access to your existing Mapbox account, another option is to set up a new Mapbox account and create a new key. We have the steps to set up a key here. Once the new key is added to Stockist, your map should start working again shortly. You don’t need to re-enter your store listings or any other settings.

Other issues

If you’ve checked both items above but still see an issue, please get in touch with our support team through the "Contact us" page of the dashboard.
In rare cases we've seen other issues affect the map -  for example, a style rule from your site’s theme could accidentally be hiding the image elements within the map.

We’re happy to help confirm if the issue is caused by your Mapbox key or another problem.

Related Articles