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 style ID or tileset 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 tileset 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):{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 for both tilesets and Classic styles 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):{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. If you have any Mapbox Studio Classic projects or styles, you can find their IDs on your Classic 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:

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

Your invoice is unpaid

If you exceed the API requests included in the free tier and do not have a valid payment method for your account, your account will be disabled and your maps will no longer be displayed. After the first failed payment, you will have a brief grace period to visit your Account settings page and add or update your payment information before your account is disabled.

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

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

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

// detect the map's new width and height and resize it

Read more about resize in the documentation.


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

// your code that shows the map div

// invalidate the size of your map

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
Was this page helpful?