> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/llms.txt) # Troubleshooting SVG image errors in Mapbox Studio The Mapbox Studio style editor supports the SVG format for [icons](https://docs.mapbox.com/help/glossary/icon/) and patterns. Studio uses SVG because it's scalable and supports devices with a range of screen resolutions. Behind the scenes, the [Mapbox Styles API](https://docs.mapbox.com/api/maps/styles/) uses the source SVGs to render [sprites](https://docs.mapbox.com/help/glossary/sprite/) (collections of PNG) at a variety of resolutions, then delivers the proper sprite based on a user's device. For example, if a user views your map on a device with a high resolution screen, they will receive a 2x sprite. If a user views your map on a device with a low resolution screen, they receive a 1x sprite. ## Common issues Sometimes SVGs fail to upload or upload successfully, but do not appear as expected. Here are some common issues and suggestions for troubleshooting them. ### Black images with no color If you are able to add your SVG to Mapbox Studio, but it shows up as black, it may be because you are using the [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element to assign style properties rather than using inline `style` attributes. Mapbox Studio does not support style properties added in the [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element. If you use Adobe Illustrator to create your SVG, choose **Export** or **Save As** and follow the instructions in the [Create SVG icons in Adobe Illustrator](#create-svg-icons-in-adobe-illustrator) section of this guide to format the SVG file correctly for use in Mapbox Studio. ### Blank images ![Mapbox Studio custom icons appearing blank](https://docs.mapbox.com/help/assets/ideal-img/troubleshooting--blank-svg.c648eb6.480.jpg) Custom images imported with Mapbox Studio can appear blank if the original SVG files contain no vector content, or no content in supported attributes. For example, you can successfully upload an SVG file with Mapbox Studio, but if the file includes raster content in an unsupported attribute such as `` and does not include *vector content in a supported attribute*, such as ``, the image will appear as a blank canvas containing no visible content. For a full list of which SVG elements and attributes are supported and unsupported, see [Unsupported SVG elements and attributes](#unsupported-svg-elements-and-attributes) on this page. ### Sketch icons not rendering 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`. ### "Icon upload failed" error If your icon fails to upload, it's likely either because the SVG is too large or the file is not a valid SVG. (For the list of SVG elements and attributes that the Mapbox uploader supports, see the [Mapnik SVG support page](https://github.com/mapnik/mapnik/wiki/SVG-support).) We recommend you make sure that: - The images you're uploading are smaller than the sprite dimension limit: 512 x 512px. Learn more about [how sprites work](https://docs.mapbox.com/help/glossary/sprite/). - There are no syntax errors in your SVG file. ### Size property causing icon to look 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. To keep your icons crisp, set the `size` property to `1`. And if you want to display a larger image on the map, upload a larger SVG. ## 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 an `.svg` file from Illustrator: **Export** and **Save As**. ### Export - 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: ![adobe illustrator SVG export settings](https://docs.mapbox.com/help/assets/ideal-img/svg_export_illustrator_setting.480.png) ### 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: ![adobe illustrator SVG export settings](https://docs.mapbox.com/help/assets/ideal-img/svg_saveas_illustrator_setting.5a5162b.480.png) ## Unsupported SVG elements and attributes The Mapbox uploader does not support all possible SVG elements and attributes. For a full list of supported and unsupported SVG elements and attributes, see the [Mapnik SVG support page](https://github.com/mapnik/mapnik/wiki/SVG-support).