apache/superset · error · ValidatorSQL400Error

%(validator)s was unable to check your query. Please recheck

Error message

%(validator)s was unable to check your query.
Please recheck your query.
Exception: %(ex)s

What it means

The generic except-Exception handler in validate_sql wraps any failure of self._validator.validate(sql, catalog, schema, model) into a SupersetError saying '%(validator)s was unable to check your query... Exception: %(ex)s'. This is the catch-all for the external SQL validator backend (e.g., the Presto/Trino validator) blowing up, including the utils.timeout exception when validation exceeds SQLLAB_VALIDATION_TIMEOUT seconds. The error becomes ValidatorSQL400Error if the exception text contains a standalone 3-digit 4xx code (regex `([\W]|^)4\d{2}([\W]|$)`), otherwise ValidatorSQLError (422).

Source

Thrown at superset/commands/database/validate_sql.py:143

            )
            raise ValidatorSQL400Error(superset_error) from ex
        except Exception as ex:
            logger.exception(ex)
            superset_error = SupersetError(
                message=__(
                    "%(validator)s was unable to check your query.\n"
                    "Please recheck your query.\n"
                    "Exception: %(ex)s",
                    validator=self._validator.name,
                    ex=ex,
                ),
                error_type=SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
                level=ErrorLevel.ERROR,
            )

            # Return as a 400 if the database error message says we got a 4xx error
            if re.search(r"([\W]|^)4\d{2}([\W]|$)", str(ex)):
                raise ValidatorSQL400Error(superset_error) from ex
            raise ValidatorSQLError(superset_error) from ex

    def validate(self) -> None:
        # Validate/populate model exists
        self._model = DatabaseDAO.find_by_id(self._model_id)
        if not self._model:
            raise DatabaseNotFoundError()

        spec = self._model.db_engine_spec
        validators_by_engine = app.config["SQL_VALIDATORS_BY_ENGINE"]
        if not validators_by_engine or spec.engine not in validators_by_engine:
            raise NoValidatorConfigFoundError(
                SupersetError(
                    message=__(
                        "no SQL validator is configured for %(engine_spec)s",
                        engine_spec=spec.engine,
                    ),
                    error_type=SupersetErrorType.GENERIC_DB_ENGINE_ERROR,

View on GitHub (pinned to f4587218dd)

Solutions

1. If the message says the query exceeded the timeout, raise SQLLAB_VALIDATION_TIMEOUT in superset_config.py or validate a smaller query.
2. Verify the validator backend configured under SQL_VALIDATORS_BY_ENGINE is deployed, reachable from Superset, and healthy.
3. Check the logged exception (logger.exception) for the root cause — 4xx-class messages become 400, everything else 422.
4. If the validator is flaky or unnecessary, remove the engine from SQL_VALIDATORS_BY_ENGINE so the UI skips server-side validation.

Example fix

# superset_config.py — before
SQLLAB_VALIDATION_TIMEOUT = 2

# after
SQLLAB_VALIDATION_TIMEOUT = 15

# Verify the validator backend is up before submitting validation
def validator_backend_healthy(app, engine: str) -> bool:
    from superset.sql_validators import get_validator_by_name
    name = app.config["SQL_VALIDATORS_BY_ENGINE"].get(engine)
    validator = get_validator_by_name(name) if name else None
    return validator is not None and getattr(validator, "available", lambda: True)()

from superset.commands.database.exceptions import ValidatorSQLError, ValidatorSQL400Error
import time
for attempt in range(2):
    try:
        return ValidatorSQLCommand(db_id, payload).run()
    except ValidatorSQL400Error:
        raise  # client/query problem — not retryable
    except ValidatorSQLError as ex:
        if "timeout" in str(ex).lower() and attempt == 0:
            time.sleep(1)
            continue  # transient timeout: retry once
        raise

When it happens

Trigger: POST /api/v1/database/validate_sql for an engine with a configured validator where: the validator HTTP service (e.g., a Presto validator endpoint) is down or returns an error; the query takes longer than SQLLAB_VALIDATION_TIMEOUT seconds ('The query exceeded the N seconds timeout.'); the validator client raises a network or parsing exception.

Common situations: SQLLAB_VALIDATION_TIMEOUT left at default while validating huge queries; the validator service URL in config is stale/unreachable in the deployment; validator version mismatch with the engine; proxies returning HTML error pages that the client cannot parse (surfacing as a generic exception).

Related errors

• No validator named %(validator_name)s found (configured for
• An unexpected error occurred
• ex.errors[0]
• Template processing failed: %(ex)s
• Database not found.

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