apache/superset · error · SqlLabException

GENERIC_DB_ENGINE_ERROR

GENERIC_DB_ENGINE_ERROR

Error message

Failed to execute %(query)s: The query record was not created as expected Please contact an administrator for further assistance or try again.

What it means

Raised in ExecuteSqlCommand._save_new_query (superset/commands/sql_lab/execute.py:197) as SqlLabException with SupersetErrorType.GENERIC_DB_ENGINE_ERROR when self._query_dao.create(query) throws a SQLAlchemyError. The Query record that SQL Lab persists before dispatching work could not be written to Superset's metadata database; the original SQLAlchemyError is chained. The subsequent db.session.commit() is the deliberate early commit that makes async Celery execution possible.

Source

Thrown at superset/commands/sql_lab/execute.py:197

    def _save_new_query(self, query: Query) -> None:
        """
        Saves the new SQL Lab query.

        Committing within a transaction violates the "unit of work" construct, but is
        necessary for async querying. The Celery task is defined within the confines
        of another command and needs to read a previously committed state given the
        `READ COMMITTED` isolation level.

        To mitigate said issue, ideally there would be a command to prepare said query
        and another to execute it, either in a sync or async manner.

        :param query: The SQL Lab query
        """
        try:
            self._query_dao.create(query)
        except SQLAlchemyError as ex:
            raise SqlLabException(
                self._execution_context,
                SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
                "The query record was not created as expected",
                ex,
                "Please contact an administrator for further assistance or try again.",
            ) from ex

        db.session.commit()  # pylint: disable=consider-using-transaction

    def _validate_access(
        self, query: Query, template_params: Optional[dict[str, Any]] = None
    ) -> None:
        try:
            self._access_validator.validate(query, template_params)
        except Exception as ex:
            raise QueryIsForbiddenToAccessException(self._execution_context, ex) from ex

    def _set_query_limit_if_required(

View on GitHub (pinned to f4587218dd)

Solutions

1. Check the chained SQLAlchemyError and Superset server logs to identify the exact metadata-DB failure
2. If schema-related, run `superset db upgrade` so the Query model matches the database
3. Verify metadata DB connectivity/health and connection pool sizing under load
4. For duplicate client_id races, generate a fresh client_id per submission instead of reusing one

try:
    ExecuteSqlCommand(ctx).run()
except SqlLabException as ex:
    if ex.error_type == SupersetErrorType.GENERIC_DB_ENGINE_ERROR and "query record was not created" in str(ex):
        root = ex.__cause__  # SQLAlchemyError from metadata DB
        # schema drift? run `superset db upgrade`; db down? check metadata DB health
        

When it happens

Trigger: Any metadata-DB write failure at query creation: schema drift (Query table migration not applied), constraint violation on the query row (e.g. duplicate client_id), metadata database down/restarted, or connection pool exhaustion at high concurrency.

Common situations: Upgrading Superset without running `superset db upgrade` so the query table schema mismatches; Postgres/MySQL metadata DB briefly unavailable; unique-constraint races on client_id from double-submitted queries.

Related errors

• Failed to execute %(query)s: {exception message}
• The database referenced in this query was not found. Please
• Database could not be created.
• Unknown type: {native_type}
• An error occurred while creating the value.

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