What causes "Failed to execute %(query)s: {exception message}" in apache/superset?

Inspect the exception's __cause__ (or server logs — the original is logged) to find the real failure; the SqlLabException itself is just a wrapper

apache/superset · error · SqlLabException

Failed to execute %(query)s: {exception message}

Error message

Failed to execute %(query)s: {exception message}

What it means

Raised in ExecuteSqlCommand.run() (superset/commands/sql_lab/execute.py:125) as SqlLabException wrapping any exception that is not itself SupersetErrorException/SupersetErrorsException. It is the catch-all boundary for SQL execution: the original exception is chained (raise ... from ex) and paired with the execution context, so the true root cause (engine error, driver error, etc.) is in the __cause__, not this message. The message template 'Failed to execute %(query)s' gets the query text interpolated.

Source

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

            self._execution_context_convertor.set_payload(
                self._execution_context, status
            )

            # save columns into metadata_json
            self._query_dao.save_metadata(
                self._execution_context.query, self._execution_context_convertor.payload
            )

            return {
                "status": status,
                "payload": self._execution_context_convertor.serialize_payload(),
            }
        except (SupersetErrorException, SupersetErrorsException):
            # to make sure we raising the original
            # SupersetErrorsException || SupersetErrorsException
            raise
        except Exception as ex:
            raise SqlLabException(self._execution_context, exception=ex) from ex

    def _try_get_existing_query(self) -> Query | None:
        return self._query_dao.find_one_or_none(
            client_id=self._execution_context.client_id,
            user_id=self._execution_context.user_id,
            sql_editor_id=self._execution_context.sql_editor_id,
        )

    @classmethod
    def is_query_handled(cls, query: Query | None) -> bool:
        return query is not None and query.status in [
            QueryStatus.RUNNING,
            QueryStatus.PENDING,
            QueryStatus.TIMED_OUT,
        ]

    def _run_sql_json_exec_from_scratch(self) -> SqlJsonExecutionStatus:
        self._execution_context.set_database(self._get_the_query_db())

View on GitHub (pinned to f4587218dd)

Solutions

Inspect the exception's __cause__ (or server logs — the original is logged) to find the real failure; the SqlLabException itself is just a wrapper
Fix the underlying cause: connectivity, driver version, SQL validity, or worker resources
If the cause is transient (connection blip), retrying the query after reconnecting is reasonable

Example fix

# inspecting the root cause of the catch-all
try:
    ExecuteSqlCommand(...).run()
except SqlLabException as ex:
    root = ex.__cause__ or ex
    logger.error("query failed: %s", root)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    ExecuteSqlCommand(ctx).run()
except SqlLabException as ex:
    root = ex.__cause__ or ex
    # branch on the ROOT cause (driver/network/OOM), not on SqlLabException itself
    log_and_surface(root)

Prevention

Always inspect __cause__/server logs — SqlLabException is a wrapper, not the diagnosis
Keep database drivers and engine specs up to date to reduce unexpected exceptions

When it happens

Trigger: Any unexpected failure during query dispatch — database driver errors, connection drops mid-execution, unexpected engine-spec exceptions, or serialization failures — anything the specialized Superset error paths do not already handle.

Common situations: Network interruption to the database, driver incompatibilities after an upgrade, out-of-memory in the worker, or unhandled edge cases in engine specs.

Related errors

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