CARTO.js - Error messages

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	Description
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.

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.