Skip to main content

Frequently Asked Questions

Join the Mapbox Developers Discord Communityarrow-right
lightning
Public beta
Mapbox Tiling Service is in public beta. All features and workflows are subject to potential changes.

Answers to commonly asked questions for users of the Mapbox Tiling Service (MTS).

What is the difference between errors and warnings on an MTS tileset job?​

Both errors and warnings are arrays in the response data from the GET /jobs/:job_id and GET /jobs endpoints. A tileset job will only have an errors array if it has failed, describing why it failed. A successful job will have a warnings array if one or more features were dropped from the resulting tileset.

There are gaps of missing data in my tiles​

If you notice that your MTS tileset is missing points, lines, or polygons, it’s likely that MTS dropped some features because the layer size was approaching the maximum allowed size of 1250 KB. If you use the GET /jobs/:job_id endpoint for this tileset job, you will see warnings about how many tiles dropped features and a list of example tiles so you can diagnose the problem.

To avoid hitting the 1250 KB limit, you should reduce the number and size of features in each layer. You can do this by:

  • Specifying "tiles": { "id": null } to remove feature IDs from the output tiles.
  • Setting "features": { "attributes": { "allowed_output": [ … ] } } to remove all but the needed attributes.
  • Using "features": { "attributes": { "set": { … } } } to set the value of unneeded attributes to null.
  • Using integer values for attributes instead of floating point or string values.
  • Using the same attribute values between features instead of unique values.
  • Using "features": { "filter": … } with a [ "zoom" ] expression to reduce the number of features at low zoom levels.
  • Using "tiles": { "union": [ … ] } to merge features with the same attributes into a single feature.
  • Setting "tiles": { "extent": …, "buffer_size": … } to reduce the geometry resolution within tiles and the number of features mirrored from adjacent tiles.
  • Setting "features": { "simplification": … } to reduce the geometric complexity of features.

If none of these options are practical for your data, or are not enough, you can specify a higher layer_size of up to 2500 in your recipe. You can find the necessary layer_size for your data and recipe by consulting the capped_list in the information about your tiling job.

My minzoom is different than expected​

MTS tries to generate tiles for every requested zoom level. If the zoom levels in a tileset do not match the zoom levels in the corresponding recipe, this is due to features being filtered out based on the rules you have provided, which led to empty tiles at these zooms.

For example, if you specify a minzoom level of 6 but your filtering syntax only starts accepting features at zoom 8, once processing is complete MTS will dynamically set the tileset's minzoom to 8 since there are no tiles to be requested at zoom 6 or 7.

There are "notches" in my LineStrings at high zooms​

Notches in LineStrings happen when high zoom tiles do not have buffers that are large enough. To avoid possible buffer-edge artifacts, set your buffer_size to something larger than the default of 0.5. The recommended value is 6.

The features in my vector tiles have different IDs than the features in my source data​

Vector tiles only support integer-based identifiers. If you provide an ID in the tileset source in any format other than integers, MTS will generate an integer hash of this value to use as the feature ID.

If you need to keep the original source IDs, you can do either of the following:

  • Use integer IDs in the source data.
  • Save the original ID of the feature as an attribute in the vector tiles using the set option in your recipe.

A feature I expected to be in my new tileset isn't there​

If a feature that you expected to see is not in the new tileset, it might have been dropped for one of the following reasons:

  • The tileset source data was not valid GeoJSON. You can diagnose the problem by using the Tilesets CLI's validate-source command to validate your source data.
  • The feature was filtered out by your recipe. For more information on how and why a recipe might filter out a feature, see the Mapbox Tiling Service recipe reference.
  • The feature has been simplified away at certain zoom levels. For more information on feature simplification, see the Mapbox Tiling Service recipe reference.

I'm not able to use GeometryCollection features in my tileset source​

Tileset sources do not support GeoJSON GeometryCollection features. If you have GeometryCollection features in your source data, you should split each of its sub-features into a unique, individual feature.

There are no features in my tileset when I click "zoom to data" in Mapbox Studio​

Depending on how your data is distributed or the zoom range you choose, knowing where your data is can be a challenge. Mapbox Studio tries to help you visualize your data at the right location, but due to how it makes this calculation, you may not see any features if there are not any at the mathematical center of the tileset source used to create the tileset. If this occurs, you will need to manually click and drag the map to your feature locations, rather than being able to click "zoom to data".

Objects and arrays in feature properties are being dropped​

According to the Mapbox vector tile spec, object and array values are not supported in feature.properties. Any non-primitive types included in feature.properties will be dropped when you publish your tileset source to MTS. To get around this issue, you can convert objects like below:

{
  "foo": {
    "bar": "hoge"
  }
}

to

{
  "foo.bar": "hoge"
}

For arrays, depending on how you are using this on the client side, you can transform them like below:

{
  "foo": [
     "bar",
     "hoge"
  ]
}

to

{
  "foo_0": "bar",
  "foo_1": "hoge",
  "foo_count" 2
}
Join the Mapbox Developers Discord Communityarrow-right
Was this page helpful?