apache/superset · error · DatabaseConnectionFailedError

Connection failed, please check your connection settings

Error message

Connection failed, please check your connection settings

What it means

DatabaseConnectionFailedError is raised in validate() when ping(engine) either throws a non-OAuth2 exception or returns a non-alive status. It is the generic 'cannot reach the database' failure during a permission sync, wrapping the original driver exception as __cause__.

Source

Thrown at superset/commands/database/sync_permissions.py:125

        if not self.username or not (
            user := security_manager.get_user_by_username(self.username)
        ):
            raise UserNotFoundInSessionError()
        self._user_id = user.id

        with self.db_connection.get_sqla_engine() as engine:
            try:
                alive = ping(engine)
            except Exception as err:
                if (
                    self.db_connection.is_oauth2_enabled()
                    and self.db_connection.db_engine_spec.needs_oauth2(err)
                ):
                    raise MissingOAuth2TokenError() from err
                raise DatabaseConnectionFailedError() from err

        if not alive:
            raise DatabaseConnectionFailedError()

    def run(self) -> None:
        """
        Triggers the perm sync in sync or async mode.
        """
        self.validate()
        if self.async_mode:
            sync_database_permissions_task.delay(
                self.db_connection_id, self._user_id, self.old_db_connection_name
            )
            return

        self.sync_database_permissions()

    @transaction(
        on_error=partial(on_error, reraise=DatabaseConnectionSyncPermissionsError)
    )
    def sync_database_permissions(self) -> None:

View on GitHub (pinned to f4587218dd)

Solutions

Use 'Test Connection' in the database edit dialog and fix host/port/credentials
Verify network reachability from the Superset host (DNS, firewall, VPN)
Inspect the chained exception (err) in logs for the driver-level cause
If the cause is actually OAuth2, complete the OAuth2 flow (see MissingOAuth2TokenError)

Example fix

// before
 conn = sqlalchemy.create_engine("postgresql://u:p@db:5432/x")

// after
 conn = sqlalchemy.create_engine("postgresql://u:p@db.example.com:5432/x")  # correct host

Defensive patterns

Strategy: retry

Validate before calling

from superset.utils.core import ping

with db_conn.get_sqla_engine() as engine:
    if not ping(engine):
        raise ConnectionError("database unreachable; fix connection settings")

Try / catch

try:
    cmd.run()
except DatabaseConnectionFailedError as e:
    cause = e.__cause__  # driver-level detail
    # fix settings or retry with backoff for transient faults
    ...

Prevention

Run 'Test Connection' after any credential/network change
Wrap syncs with bounded retry for transient outages

When it happens

Trigger: Wrong host/port/credentials in the connection settings; database server down or unreachable from Superset; firewall/DNS issues; the SQLAlchemy URL parameters are invalid.

Common situations: Expired DB passwords, VPN/network changes, database migrated to a new host, TLS settings mismatch between Superset and the DB server.

Related errors

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