Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Questions  /  Your Account & Plan  /  Troubleshooting

How to submit a bug in CARTO

Best practices to submit a bug in CARTO

Who is this for?

  • :computer: Developers and data scientists
  • :busts_in_silhouette: CARTO clients and users that are not developers should follow general guidelines described in CARTO's support details page

A bug is a problem causing CARTO platform to stop working or produce invalid output. A bug can be an error, mistake, defect or fault, which may cause failure or deviation from expected results.

When should I report a bug?

  • :bug: You found a specific and repeated problem in the platform
  • :collision: Your map or app stops working every time you follow the same workflow
  • :exclamation: You are getting the same unknown error when running a Python script

Why should I report a bug?

If your bug report is effective, then its chances to get fixed are higher. As a result, the problem that was blocking your workflow will go away. But more importantly, the fix will help the rest of CARTO users.

Where should I report a bug?

Builder maps

If you found a bug when You should open a new issue in GitHub’s cartodb repository filling the template with as much details as possible.

Tip: Adding a .carto file to the report is the best way to help developers to replicate the problem on their end.

CARTO applications

CARTO applications can be built using a mix of libraries and APIs. So depending on the bug origin, the report should be posted on the right repository.

:page_facing_up: If your application is built with CARTO.js technology and the bug is related to layers and/or dataviews, open an issue at carto.js repository.

:page_facing_up: If your application is built with CARTO VL technology and the problem is related to layer styling and/or vector rendering, open an issue at carto-vl repository.

:page_facing_up: If your bug appears when building an application with Airship layouts and web components, open an issue at airship repository.

:page_facing_up: If you are using a Python script and found any unknown and undocumented error when working with CARTOframes or CARTO’s Python SDK, open an issue at cartoframes or carto-python repositories, respectivelly.

How should I report a bug?

Avoid duplicates

Check the whole list of known bugs. At times, the developers might have known the issue and ignored for a future release.

Note: Keep in mind that sometimes what you consider a bug, it could be a problem of misunderstanding or lack of knowledge. Reviewing HELP articles and GIS StackExchange QAs is a good practice that could help users to solve this kind of situations.

Be specific

Do not write an essay about the problem. Be specific and to the point. Try to summarize the problem in minimum words yet in an effective way. Do not combine multiple problems even if they seem to be similar.

Being specific is especially important when chosing a title for your bug report. The title (and summary) will make the bug report searchable and uniquely identifiable. A good and bad example are shown below:

:+1: My Builder map returns an unknow error when styling by numeric values.

:-1: My map is not working.

Steps To Reproduce (STR)

If your bug is not reproducible, then it will never get fixed. You should clearly mention the steps to reproduce the bug. Do not assume or skip any reproducing step. A bug which is described step by step is easy to reproduce and fix.

What’s next?

:ballot_box_with_check: Learn how to download Builder maps as .carto reading this tutorial.

:ballot_box_with_check: Check this issue to see a good bug report example.

:ballot_box_with_check: Check this example to learn how to hadle errors in CARTO.js.