Blank or missing map tiles

Maps can fail to load for a variety of reasons related to your Mapbox account, your code, the browser you are using, the network you are on, or your computer. This guide will walk you through how to troubleshoot some common reasons maps fail to load.

Your account is over its usage limits

If you exceed the map view limit, you will receive an email with an invoice for overages at the end of your billing cycle. You will have a brief grace period to visit your Billing page and add or update your payment information before your account is disabled.

If you exceed the map view limit for your current plan and do not have a valid payment method for your account, your account will be disabled and your maps will no longer be displayed.

If your account is disabled, you can reactivate it following these steps:

  • Log in to your Mapbox account at mapbox.com/studio.
  • After logging in, choose a plan from the prompt that is displayed.
  • After choosing a plan, update the payment information on your Billing page.
  • Pay the outstanding invoice.

Your tiles will be restored shortly after you have reactivated your account.

Your style ID or map ID is invalid

If you are using a Mapbox Studio style, check to make sure the style URL you are using contains a valid style ID. If you are using a Classic style, make sure the map ID is valid.

Style ID

You can test the style ID by finding the style URL you’ve added to your code, copying the string after the last /, and navigating to the following URL in your web browser (be sure to replace username with your own and use the string you copied from your style URL to replace the style_id):

https://api.mapbox.com/styles/v1/{username}/{style_id}?access_token=<your access token here>

If a JSON object is not returned, your style ID is invalid. You can find valid style URLs on your Styles page. You may also use any of the Mapbox styles.

Map ID

You can test the map ID for both Classic styles and tilesets by finding the map ID you’ve added to your code and navigating to the following URL in your web browser (be sure to replace the {map_id} with your own):

https://api.mapbox.com/v4/{map_id}/page.html?access_token=<your access token here>

If this page doesn’t load, your map ID is invalid. You can find valid map IDs on your Projects, Classic, and Tilesets pages. You may also use any of the Mapbox map IDs.

Your access token is invalid

You can test your access token by navigating to the following URL in your web browser, making sure that you’ve replaced {access_token} with the access token used in your code:

https://api.mapbox.com/v4/mapbox.streets/page.html?access_token={access_token}

If this page doesn’t load, your access token is faulty. Head to the API access tokens section of your Mapbox Account page, generate a new access token, and try again.

You’re using v3 of the Mapbox Maps API

Check your code to see if you’re requesting a map from v3 of the Mapbox Maps API. If you’re still using v3, you’ll need to update to v4. When updating to v4 of the Mapbox Maps API, you’ll also need to make sure to include one of your access tokens with the request. See the Mapbox Maps API documentation for more info.

Your map is hidden

If you’re hiding your map initially with CSS rules like display:none, then showing it dynamically with JavaScript, it may have some problems appearing and sizing correctly.

The map can’t figure out its own size when it’s hidden from the page, since it doesn’t have a size in the browser’s calculation.

To detect and resize your map with Mapbox GL JS, you can call map.resize(). If you’re using Mapbox.js, you can call the map.invalidateSize() method.

Mapbox GL JS

When working with Mapbox GL JS, call map.resize() on the map object after its containing element is resized or shown:

// your code that shows the map div
$('#map-div').show();

// detect the map's new width and height and resize it
map.resize();

Read more about resize in the documentation.

Mapbox.js

When working with Mapbox.js, call map.invalidateSize() after showing the map:

// your code that shows the map div
$('#map-div').show();

// invalidate the size of your map
map.invalidateSize();

Read more about invalidateSize in the mapbox.js documentation.

WebGL is not supported

Mapbox GL JS maps (including the Mapbox Studio style editor and dataset editor) can fail to display because of issues with your browser, your network, your computer, or some combination of all three. WebGL compatibility can be tricky to troubleshoot and, but here are some general guidelines and resources:

  • Is WebGL supported and enabled in your current browser? Mapbox GL JS and Mapbox Studio are compatible with most modern browsers, but require that WebGL is supported and enabled.
  • Are you using a browser that supports the specific Mapbox product you are trying to use? Read more about browser support by product in our Browser support guide.
  • Does the device you are using support WebGL? You will need to refer to the technical specifications for your specific device.
  • Are you trying to access Mapbox products from behind a firewall? If you’re interacting with the Mapbox REST APIs and having trouble getting a response, you can try white-listing the domain api.mapbox.com.