CARTO.js

Integrate interactive maps and location data into your web applications and websites.

This library is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our current CARTO for deck.gl library here

Errors

CARTO.js emits error objects when something goes wrong. Errors appear in your developer console if not caught. The error object has a code and a description to help you identify the problem and troubleshoot.

CARTO.js API Error Codes

If you encounter an error while loading CARTO.js, the following table contains a list of known errors codes and possible solutions.

Error Code
Message
api-key-required

apiKey property is required.
api-key-string

apiKey property must be a string.
username-required

username property is required.
username-string

username property must be a string.
non-valid-server-url

serverUrl is not a valid URL.
non-matching-server-url

serverUrl doesn't match the username.

CARTO.js Error Codes

If you find a validation error on Chrome JavaScript Console, Firefox Web Console, or any other equivalent tools in your browser, please reference the tables below to find explanations for the validation errors. Each table gives specific error information for the different components of CARTO.js.

Dataview

Error Code
Message
source-required

Source property is required.
column-required

Column property is required.
column-string

Column property must be a string.
empty-column

Column property must be not empty.
filter-required

Filter property is required.
time-series-options-required

Options object to create a time series dataview is required.
time-series-invalid-aggregation

Time aggregation must be a valid value. Use carto.dataview.timeAggregation.
time-series-invalid-offset

Offset must an integer value between -12 and 14.
time-series-invalid-uselocaltimezone

useLocalTimezone must be a boolean value.
histogram-options-required

Options object to create a histogram dataview is required.
histogram-invalid-bins

Bins must be a positive integer value.
formula-options-required

Formula dataview options are not defined.
formula-invalid-operation

Operation for formula dataview is not valid. Use carto.operation.
category-options-required

Category dataview options are not defined.
category-limit-required

Limit for category dataview is required.
category-limit-number

Limit for category dataview must be a number.
category-limit-positive

Limit for category dataview must be greater than 0.
category-invalid-operation

Operation for category dataview is not valid. Use carto.operation.
category-operation-required

Operation column for category dataview is required.
category-operation-string

Operation column for category dataview must be a string.
category-operation-empty

Operation column for category dataview must be not empty.

Filter

Error Code
Message
invalid-bounds-object

Bounds object is not valid. Use a carto.filter.Bounds object.

Layer

Error Code
Message
non-valid-source

The given object is not a valid source. See carto.source.Base.
bad-layer-type

The given object is not a layer.
non-valid-style

The given object is not a valid style. See carto.style.Base.
source-with-different-client

A layer can't have a source which belongs to a different client.
style-with-different-client

A layer can't have a style which belongs to a different client.

Source

Error Code
Message
query-required

SQL Source must have a SQL query.
query-string

SQL Query must be a string.
no-dataset-name

Table name is required.
dataset-string

Table name must be a string.
dataset-required

Table name must be a string.

Style

Error Code
Message
required-css

CartoCSS is required.
css-string

CartoCSS must be a string.

CARTO.js Platform Error Codes for Developers

If you find an error on Chrome JavaScript Console, Firefox Web Console, or any other equivalent tools on your browsers (regarding platform (aka. backend services)), please reference the table below to find explanations for the error codes.

Error Code
Message
Description
over-platform-limits

You are over platform's limits.

In order to guarantee the performance of those APIs for every user of the CARTO platform and prevent abuse, we have set up some general limitations and restrictions on how they work.

       

Learn about fundamentals of [limits](/developers/fundamentals/limits/) in CARTO.
generic-limit-error

The server is taking too long to respond.

Due to poor conectivity or a temporary error with our servers, we cannot handle your request. Please try again soon.

Checking Errors in your Browser

CARTO.js writes error messages to window.console if they are not caught. Please check the developer documentation for your browser in order to understand how you can check it.

If any errors occurred when loading CARTO.js, they appear as one or more lines in the console. You can check the [error codes table](#errors above to find te error in the error message. You can also find the details about the error message in the Full Reference API.

Ensure that you are using a supported browser.