メインコンテンツまでスキップ

Upload data to Mapbox

This guide covers common errors and pitfalls when uploading data to Mapbox, whether you're uploading vector data or GeoTIFFs, with advice on how to resolve them.

Mapbox Console upload limits​

All uploads made through the Mapbox Console, whether by dragging data in the Data Workbench tab or adding data inside a style, are subject to a 300 MB file size limit. If your file exceeds this limit, use the Mapbox Tiling Service (MTS) directly to upload your data to Mapbox.

For a full list of supported file types, size limits, and monthly free limits, see the supported file types.

Raster uploads​

MBTiles uploads​

When uploading raster MBTiles to the Mapbox Console, use 512x512 tiles.

TIFF uploads​

There are two requirements for TIFFs:

  • Only 8-bit GeoTIFFs are supported. Run gdalinfo to find your GeoTIFF's resolution.
  • Mapbox only accepts TIFFs with georeferencing information (GeoTIFFs). Make sure your TIFF is georeferenced before trying to upload.

If you are attempting to upload large TIFFs (multi GBs), here are some ways you can optimize your TIFF before uploading:

  • Reproject to Web Mercator EPSG:3857.
  • Set blocksize to 256x256.
  • If compression is needed, use LZW.
  • Remove Alpha band, if applicable.

Common raster upload errors​

MessageDescriptionSolution
Unknown filetypeYou have one of the following:
  • Bad TIFF files that are missing necessary information.
  • Invalid MBTiles where the MBTiles is not recognized as an SQLite database.
  • Invalid MBTiles table data where the MBTiles has data in the tile_data field of the tiles that does not represent a valid tile format (png, jpeg, or gzip compressed mapbox vector tile).
  • tmz2 files have been double zipped meaning the .zip process has been applied twice on the same file.
  • Try running gdalinfo to get more information.
  • Make sure your MBTiles file conforms to the MBTiles specification.
  • Check that the file has only been zipped once.
Error creating Mapnik Datasource: Invalid raster: Invalid pixelsize in geotransform arrayThere is a problem with the pixels in the GeoTIFF image you are uploading.There are a few situations where you may see this error:
  • The GeoTIFF image is flipped left to right
  • The GeoTIFF image is upside down.
  • The pixels in the GeoTIFF image are not roughly square.

Vector uploads: Shapefile and MBTiles​

Common Shapefile and vector MBTiles upload errors​

MessageDescriptionSolution
Metadata exceeds limit of 60kbThe TileJSON file in your MBTiles upload contains too much information.Remove extra or unneeded content from the TileJSON file (inside the MBTiles file).
Failed to find a shapefile in your zipYou tried to upload a zipfile that did not include one of the files that make up a shapefile: .shp, .shx, .dbf, .prj.Make sure your zipfile contains each of these files.
Tileset exceeds processing limit.Your MBTiles file has more items than the limit allows.Try adjusting & limiting your zoom levels.
Tile exceeds maximum size of 500k at z{zoom level}. Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.The size of a specific tile in the MBTiles file is too large.Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.
Grid exceeds maximum size of 500k at z{zoom level}. Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.The size of the grid tile in the MBTiles file is too large.Reduce the detail of data at this zoom level or omit it by adjusting your minzoom.
Invalid tile based on the Mapbox Vector Tile spec: ClosePath command count is not 1 or Invalid tile based on the Mapbox Vector Tile spec: Max count too largeOne of the tiles in your MBTiles file is invalid according to the Mapbox Vector Tile Specification.We need to make sure all vector tiles conform to the specification, so this makes sure any encoders are doing their job correctly. If you see this, contact help@mapbox.com with the error message for help.
invalid zip fileThe zipfile does not contain a valid shapefile in the root directory.Make sure your zipfile contains a .shp file and the .shp file is in the root directory (not a subdirectory within the zipped folder).
Tileset is emptyThe MBTiles file you are trying to upload is empty.Make sure the tiles table in your MBTiles file contains tiles.

Vector uploads in the Data Workbench​

This section covers troubleshooting issues related to uploading GeoJSON, GPX, KML, TSV, or KML files in the Mapbox Console. Files uploaded in this format can be accessed and managed with the Data Workbench.

When you upload data in these file formats to Mapbox, your data is processed and normalized before it is stored. Understanding these rules can help you avoid unexpected results.

Property names​

Upon ingestion, property names on your features must follow these rules:

  • Must be a non-empty string. Properties with an empty-string name are discarded.
  • Must start with a letter (A-Z, a-z) or an underscore (_).
  • May only contain letters, digits (0-9), and underscores.

Property names that don't meet these requirements are automatically sanitized to make them compliant. The exception is empty-string names, which are discarded entirely.

Property values and type inference​

When data is ingested, Mapbox tries to infer a type for each property based on its values. Properties where every record's value is null are discarded.

Appending or editing data​

When you append new data or edit existing records in a table:

  • New or edited records must conform to the existing table schema. If a column already exists with a defined type, the type of any incoming value for that column must match.
  • If new or edited records contain columns not yet defined in the table, the schema is updated to include the new columns using their inferred type.

Common Data Workbench upload errors​

MessageDescriptionSolution
Unsupported CRS, expected WGS84Vector data uploaded to Mapbox has to be in the WGS84 coordinate system.Use a tool like QGIS to reproject your data to WGS84.
No valid features foundNo valid features found with latitude and longitude information.Make sure that your data has been geocoded so it contains coordinate data. Use the Mapbox Geocoding API to batch-geocode your data.
Invalid file: Unexpected format: JSON, but neither GeoJSON nor TopoJSONThe file you uploaded is valid JSON but is not recognized as GeoJSON or TopoJSON. This means the JSON structure is missing required fields like "type": "FeatureCollection".Make sure your file conforms to the GeoJSON specification or the TopoJSON specification. You can validate your GeoJSON with geojson.io. If your data is plain JSON (such as an API response), you'll need to convert it to GeoJSON before uploading.
Processed with warning: * Interpreted as WGS84 for compatibilityData was in a different coordinate system and has been interpreted as WGS84No action needed. This is a warning.

Uploads API errors​

Common Uploads API errors​

MessageDescriptionSolution
vector_layers must be an array of layer objectsYour data source may not have any layers.Check your data source in QGIS or use ogr2ogr to make sure it is correct.
Failed to parse geojson featureYour GeoJSON file has invalid syntax.Make sure your GeoJSON is compliant with the GeoJSON specification. You can validate your GeoJSON with GeoJSON Lint.
Error creating Mapnik Datasource: Invalid geojsonMapnik is unable to process the GeoJSON file, likely due to invalid syntax.Make sure your GeoJSON is compliant with the GeoJSON specification. You can validate your GeoJSON with the geojsonhint package.
Coordinates beyond web mercator range. Please check projection and lat/lon values.The coordinates in your file are beyond the extend of Web Mercator.Check to see that your coordinates are in the correct order ([longitude, latitude]). Try visualizing your GeoJSON in geojson.io to see if geometries appear where you expect. If they do, try reprojecting to Web Mercator prior to uploading.
Tile size exceeds limit. At least one vector tile is larger than 5MB.While generating tiles from your upload, at least one tile was larger than 5MB, which is too large.Try simplifying your data where it is most dense. This typically happens with CSV point datasets where there are many millions of points in a single tile. Try using Tippecanoe to simplify and cluster points before uploading.
Invalid CSVThe CSV is invalid according to our parser. This error typically means the parser did not find the geographic lat and long columns within the first 512 bytes of the headers, though the CSV itself may also be malformed.
Dataset not found. It may have been deleted during processing into a tileset.The uploaded dataset was deleted during processing into a tileset.Try uploading the dataset again, and do not delete the dataset until the tileset processing has successfully completed.
KML does not contain any layers.Your KML file is empty.Make sure you have some layers in your data that are readable. Here's an example of a valid KML file.
X layers found. Maximum of X layers allowed.Your KML file has more than 15 layers. This can happen when combining many files into one.Make sure to split up your layers into different files before uploading to Mapbox Studio. If you must use KML and require all the layers, use kml-split, which breaks a KML into multiple files with fewer layers. Otherwise you can merge your layers into one and upload as either GeoJSON or a Shapefile.

Tips to resolve processing timeout errors​

If you receive a Processing timed out. message after a lengthy "processing" status, it is likely because your file has taken more than one hour (two hours for MBTiles files) to process and has timed out. To keep our upload queue fresh, we limit the time it takes for particularly large uploads. The following techniques can be used to update your data to improve processing time.

Prevent feature duplication​

Preventing feature duplication is important if you plan to use the Tilequery API with a custom tileset. Feature duplication in a tileset can lead to unexpected duplicate results when using the Tilequery API with the tileset, even when the dedupe option is enabled.

To prevent feature duplication when creating a new tileset, avoid using the Uploads API and use the Mapbox Tiling Service (MTS) instead to properly create globally unique IDs.

Reproject to Web Mercator​

During upload processing, we reproject all geometries to Web Mercator (EPSG:3857) before encoding into vector tiles. During the vector tile encoding process, if your data isn't Web Mercator, each vertex must be reprojected during encoding, which can take a long time.

We suggest reprojecting your data before uploading to skip this process and speed up your upload. Here's how you can reproject your data with open source tools:

  • GDAL's ogr2ogr command line utility. The following example is how to convert a Shapefile to Web Mercator.

    ogr2ogr output.shp -t_srs "EPSG:3857" input.shp

  • QGIS allows for reprojection - Right-click your layer -> Save As -> Select "Web Mercator EPSG:3857" as the output projection.

Multipart to singlepart​

Multipart geometries can be complex – a single feature can be comprised of hundreds of thousands of polygons. These complex multipart geometries increase processing time and lead to timeouts.

To improve processing speeds, you can break each polygon into its own unique feature (singlepart) using QGIS. This will reduce the complexity per feature and allow the data to process faster. Note that each individual singlepart feature will share the attributes of the original feature.

Note that population: 100 is duplicated. If you plan on styling based on attributes such as this, be wary of splitting into singleparts!

There are a couple of helpful tools for doing this:

  • In QGIS you can use either the Vector -> Geometry Tools -> Multipart to singleparts or the Multipart Split plugin.
  • If you are using GeoJSON and Node.js, you can use the geojson-flatten module.

Simplification​

Simplifying your data means removing complexity in the vertices of your geometry. Each vertex must be translated to vector tile coordinates. The fewer vertices to translate, the faster processing becomes. Often you can simplify your data without any visual change. It's important to watch out for oversimplification, though! Oversimplifying could remove important granularity in your data as well as potentially create invalid geometries if lines begin overlapping.

Simplification tools typically take a tolerance parameter to specify how much to simplify. Some tools to use for simplifying data:

Limit large features​

Large features that span the entire dataset can slow down processing.

For example, consider this dataset of Hawaii. It contains a handful of smaller polygons that represent the islands. It also contains a large polygon that represents the surrounding water. Since the bounding box of the water polygon will intersect with nearly all the tile boundaries (gray lines), the water polygon will need to be processed for nearly every tile within this tileset.

There is no exact solution for this, since it largely depends on the dataset and how you plan to style and use the data.

Some possible solutions include:

  • Remove the large polygon if it's not necessary for your use case.

  • Split the large polygon into smaller polygons: After creating a digitized layer of smaller polygons, use that digitized layer to intersect with the large polygon and split it into pieces. Then add the newly split feature into your original dataset.

    QGIS geometry intersection - Vector -> Geoprocessing Tools -> Intersection

    Caution: This could create unwanted polygon borders, depending on how you plan to style the dataset.

Slice large contour datasets​

Large contour datasets can be particularly complex. Often they will have long, single feature linestrings wrapping across the entire dataset. Like the large polygons above, these can take a long time to process.

We recommend using GRASS's v.split function via QGIS to break lines into shorter, equal segments. Smaller geometries will improve processing speed. If the contour data is highly detailed (as in, requires zoom 22) we recommend breaking lines every 5 kilometers.

Generate tilestats for MBTiles​

We generate summary documents, known as tilestats, for uploads so Mapbox Studio can see what types of data and properties are in your spatial data. This takes quite a long time for large MBTiles files and can lead to timeouts. If you are using Tippecanoe to generate your MBTiles file you can bypass this step by using version 1.21.0 or later of Tippecanoe, which pre-generates a tilestats object. This can cut upload times in half.

If you aren't using Tippecanoe, you can still use the tile-join operation provided by Tippecanoe to generate the tilestats document. Make sure to at least use version 1.22.0.

tile-join -o with-tilestats.mbtiles original.mbtiles
このpageは役に立ちましたか？