Skip to main content

Blank or missing map tiles

Additional Developer Resources

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 explains how to troubleshoot some common reasons maps fail to load.

Your style 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.

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_MAPBOX_ACCESS_TOKEN

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.

Tileset ID​

You can test the tileset ID by finding the tileset ID you've added to your code and navigating to the following URL in your web browser (be sure to replace the {tileset_id} with your own):

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

If this page doesn't load, your tileset ID is invalid. You can find valid tileset IDs on your Tilesets page.

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/styles/v1/mapbox/light-v11.html?title=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN

If this page doesn't load, head to your Access tokens page, generate a new access token, and try again.

Your account is deactivated​

If an account exceeds the API requests included in the free tier during a billing period and the resulting invoice fails to process successfully, the account will be deactivated and requests to Mapbox services will not succeed. To reactivate an account, follow these steps:

  • Log in to the Mapbox Account.
  • Enter valid payment information into the persistent modal to be used for Upcoming invoices.
  • Navigate to the account's invoices page, and click pay to pay any Past Due invoices.

The account's services will be restored shortly after reactivation.

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 determine 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().

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.

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, 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 updating your configuration to allow the domain api.mapbox.com.
Additional Developer Resources
Was this page helpful?