apache/superset · error · SupersetErrorException

SQLLAB_TIMEOUT_ERROR

SQLLAB_TIMEOUT_ERROR

Error message

The query estimation was killed after %(sqllab_timeout)s seconds. It might be too complex, or the database might be under heavy load.

What it means

Raised in EstimateQueryCostCommand.run() (superset/commands/sql_lab/estimate.py:199) when the engine spec's estimate_query_cost call exceeds the timeout enforced by utils.timeout and throws SupersetTimeoutException; it is re-raised as SupersetErrorException with error_type SQLLAB_TIMEOUT_ERROR and HTTP 500. The timeout value comes from the SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT config, and the message interpolates that same value as sqllab_timeout.

Source

Thrown at superset/commands/sql_lab/estimate.py:199

        # (sql_lab.execute_sql_statements) so cost estimation cannot be used to
        # probe disallowed functions/tables, bypass the DML guard, or confirm
        # the existence of rows hidden by row-level security.
        sql = self._apply_sql_security(sql)

        timeout = app.config["SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT"]
        timeout_msg = f"The estimation exceeded the {timeout} seconds timeout."
        try:
            with utils.timeout(seconds=timeout, error_message=timeout_msg):
                cost = self._database.db_engine_spec.estimate_query_cost(
                    self._database,
                    self._catalog,
                    self._schema,
                    sql,
                    utils.QuerySource.SQL_LAB,
                )
        except SupersetTimeoutException as ex:
            logger.exception(ex)
            raise SupersetErrorException(
                SupersetError(
                    message=__(
                        "The query estimation was killed after %(sqllab_timeout)s "
                        "seconds. It might be too complex, or the database might be "
                        "under heavy load.",
                        sqllab_timeout=app.config["SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT"],
                    ),
                    error_type=SupersetErrorType.SQLLAB_TIMEOUT_ERROR,
                    level=ErrorLevel.ERROR,
                ),
                status=500,
            ) from ex

        spec = self._database.db_engine_spec
        query_cost_formatters: dict[str, Any] = app.config[
            "QUERY_COST_FORMATTERS_BY_ENGINE"
        ]
        query_cost_formatter = query_cost_formatters.get(

View on GitHub (pinned to f4587218dd)

Solutions

1. Retry when the database is less loaded; a one-off timeout is often transient
2. Simplify the SQL being estimated (fewer joins/subqueries) so the engine's EXPLAIN completes faster
3. Ask the operator to raise SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT in superset_config.py if estimates legitimately need longer

Example fix

# superset_config.py — raise the estimation budget
SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT = 120  # seconds, was 10

try:
    cost = EstimateQueryCostCommand(params).run()
except SupersetErrorException as ex:
    if ex.error.error_type == SupersetErrorType.SQLLAB_TIMEOUT_ERROR:
        # transient under load: retry with backoff, or skip estimation
        

When it happens

Trigger: Cost estimation against a database engine whose cost-estimate query (usually an EXPLAIN against the target database) takes longer than SQLLAB_QUERY_COST_ESTIMATE_TIMEOUT seconds — very complex SQL, huge partitioned tables, or a slow/overloaded database.

Common situations: Default estimate timeout being short while the analytical database is under load; estimators on some engines running expensive plans; network latency to remote databases.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• SYNTAX_ERROR
• DML_NOT_ALLOWED_ERROR
• Import failed for an unknown reason
• OAUTH2_REDIRECT_ERROR
• Database schema is not allowed for csv uploads.

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/d42a5d3bb74458a6. Report an issue: GitHub.