Troubleshooting: Troubleshooting SVG image errors in Mapbox Studio

The Mapbox Studio style editor supports the SVG format for icons and patterns. Studio uses SVG because it’s scalable and supports devices with a range of screen resolutions. Behind the scenes, the Style API renders sprites (collections of PNGs) at a variety of resolutions from the source SVGs and then delivers the proper sprite based on a user’s device. For example, if a user has a 2x resolution device, then they will receive a 2x sprite. If a user has a 1x resolution device, the user will receive a 1x sprite.

How create SVG icons in Adobe Illustrator

We support a wide range of SVG features, but some features aren’t available. To make sure that your vector graphics are accurately included in your maps, follow these steps:

  • Make sure everything is in vector format. If you’ve applied some Illustrator effects, go to Object > Expand Appearance. Do not include symbols or raster images as part of your SVGs, whether embedded or linked.

There are two ways to generate a .svg file from Illustrator: Export and Save As.


  • To Export, go to File > Export
  • Click the Use Artboards and enter the artboard number within the Range box
  • Click the Export button
  • In the SVG Options window, under Advanced Options panel, select Presentation Attributes as the Styling option. Uncheck the Responsive checkbox, and make sure you have a Decimal value greater than 3. Your settings should look like this:


Save as

  • To Save As, go to File > Save As, and click Save As
  • In the SVG Options window, select SVG 1.1 for SVG profiles, select Presentation Attributes for CSS Properties, select a value greater than 3 for Decimal Places, and uncheck the Responsive checkbox. Your settings should look like this:


Common issues

I get black images with no color.

Make sure you have selected Presentation Attributes and unchecked Responsive checkbox.

I used Sketch to create icons and the icons are not rendered correctly in Mapbox Studio.

The SVGs Sketch generates may include some SVG filters that can not be correctly rendered by Mapbox Studio. You can open the SVG in Adobe Illustrator and do Object > Expand Appearance.

I got “Icon upload failed” error when uploading.

The images you upload must be smaller than the sprite dimension limit, 1024px x 1024px. You can learn more about how sprite works here.

I used the size property to scale my icon and it looks blurry.

If you adjust an icon’s size in the Mapbox Studio style editor or in code, you might notice that it seems fuzzy or dithered. Icons look best when the size property is set to 1. Upload larger SVGs if you want bigger images on the map.

I want to change an icon from the Mapbox template styles, such as Mapbox Streets or Mapbox Dark …

You can get the original SVGs used in any Studio styles by clicking on the Download button of a style from the Mapbox Studio style list.

Additional questions? Ask our support team or learn more about How Mapbox Works.