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

Upload data to Mapbox

追加の開発者リソース

If you're troubleshooting an upload of your data to Mapbox, you've come to the right place! From GeoTIFFs to Shapefiles, whether you want to edit your data or style it on a map, this guide outlines common uploading errors and pitfalls with advice on how to troubleshoot them.

Mapbox Studio upload limits​

Uploads created in Mapbox Studio via the Mapbox Studio style editor, your tilesets page, or exported from a dataset using the dataset editor are subject to additional limits. These uploads cannot exceed 300 MB, and are limited to 20 uploads per month. Some file types have limits below 300 MB. See the chart below for limits by file type.

If you run into the 300 MB file limit when uploading via Studio, see the tileset upload errors section for suggested solutions.

Accepted file types and transfer limits​

The accepted file types and transfer limits for dataset and tileset uploads include:

File typeDatasetsTilesetsTransfer limits
CSV5 MB for datasets
1 GB for tilesets
GeoJSON
OGC:CRS84		5 MB for datasets
1 GB for tilesets
GeoTIFF10 GB
GPX260 MB
KML260 MB with 15 layers or fewer
MBTiles25 GB
Shapefile260 MB (combined uncompressed size of .shp and .dbf files). You must upload shapefiles as a compressed (.zip) file.

If your file size exceeds these limits, see the Troubleshooting section below.

Dataset and dataset editor limits

An extra note on dataset uploads: Multiple files can be uploaded to the same dataset without limit — they need to be loaded 5 MB at a time in the Mapbox Studio dataset editor. The size of a dataset is unlimited, but the Mapbox Studio dataset editor can only display datasets of 20 MB or smaller. Datasets that exceed 20 MB can still be downloaded from Mapbox Studio and accessed through the Mapbox Datasets API.

Raster tilesets in Mapbox Studio

When uploading raster MBTiles to Mapbox Studio, be sure to use 512x512 tiles.

TIFF uploads​

There are a couple 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.

Errors​

Upload failures directly in Mapbox Studio typically occur for two reasons:

  1. There's an explicit issue with your data.
  2. The data didn't process within one hour (two hours for MBTiles files).

If there is an explicit issue with your data, you will receive a descriptive error message when the upload fails. Each message includes an error code that is described in full below. If your upload times out, read through the troubleshooting recommendations below.

Tileset upload errors​

MessageDescriptionSolution
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.
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.
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).
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.
Tileset exceeds processing limit.Your MBTiles file has more items than the limit allows.Try adjusting & limiting your zoom levels.
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.
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.
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.
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 the MBTiles specification.
  • Check that the file has only been zipped once.
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 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, reach out to help@mapbox.com with the error message and we'll help you move forward.
[file name] exceeds the 300 MB limit. Consider using the Uploads API to upload this fileThe file you are attempting to upload is larger than the 300 MB limit for uploading using Studio.Instead of uploading your file in Studio, use the Uploads API by following the steps outlined in our API documentation. Or use one of the following approaches to get your file size below 300MB: Once you create a new file that is less than 300MB, upload this to Studio on your tilesets page or in the Mapbox Studio style editor .
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).
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.
{"message":"Not Found"}The access token used does not belong to the username used.Make sure you are using an access_token from the account associated with the username used in your request.
Tileset is emptyThe MBTiles file you are trying to upload is empty.Make sure the tiles table in your MBTiles file contains tiles.
Invalid CSVThe CSV is invalid according to our parser. It might mean the CSV is legitimately invalid but typically means the parser did not find the geographic lat and long columns within the first 512 characters of the headers.Validate your CSV using any CSV validation library or online tool. If the CSV is valid and you have many columns, move the lat and long columns to be earlier in your CSV so they are discoverable within the first 512 bytes.

Dataset upload errors​

Most dataset upload errors are related to syntax. Be sure to check your data for syntax errors before uploading. If you are working with GeoJSON data, consider using a tool like geojsonhint to lint your data before uploading. If your error is specifically related to a CSV upload, you can view our CSV file errors troubleshooting guide or investigate further by checking out the library we use to convert CSV files to GeoJSON.

MessageDescriptionSolution
Input failed old-style crs member is not recommendedYour dataset contains a crs attribute.Remove the crs attribute from your data before uploading.
Input failed. Datasets don't support GeometryCollections or null geometries.Your dataset contains one or more GeometryCollections and/or a geometry set to null.GeometryCollections and null geometries are not supported and must be removed from your dataset.

Troubleshooting​

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.

Note: the troubleshooting advice here mostly relates to tilesets, although some may be applicable to datasets as well. If you are having trouble uploading datasets and your issue is not listed here, contact support.

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, use Mapbox Tiling Service (MTS) to properly create globally unique IDs. Avoid using the Uploads API or the Mapbox Studio UI, which will not use any user-provided IDs or generate 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は役に立ちましたか？