apache/superset · error · DatabaseConnectionFailedError

Connection failed, please check your connection settings

Error message

Connection failed, please check your connection settings

What it means

DatabaseConnectionFailedError raised in CreateDatabaseCommand.run (create.py:92) when TestConnectionDatabaseCommand(...).run() blows up with any exception not in the OAuth2/SSH special-case lists. Superset deliberately opens a test connection to the target database before persisting it; any generic failure (bad credentials, DNS, firewall, missing driver, unsupported engine) becomes this error.

Source

Thrown at superset/commands/database/create.py:92

            return self._create_database()
        except (
            SupersetErrorsException,
            SSHTunnelingNotEnabledError,
            SSHTunnelDatabasePortError,
            SSHTunnelHostKeyVerificationError,
        ) as ex:
            event_logger.log_with_context(
                action=f"db_creation_failed.{ex.__class__.__name__}",
                engine=engine,
            )
            # So we can show the original message
            raise
        except Exception as ex:
            event_logger.log_with_context(
                action=f"db_creation_failed.{ex.__class__.__name__}",
                engine=engine,
            )
            raise DatabaseConnectionFailedError() from ex

        try:
            # create database and associated schema/catalog permissions
            database = self._create_database()
            add_permissions(database)
        except (
            SSHTunnelInvalidError,
            SSHTunnelCreateFailedError,
            SSHTunnelingNotEnabledError,
            SSHTunnelDatabasePortError,
        ) as ex:
            event_logger.log_with_context(
                action=f"db_creation_failed.{ex.__class__.__name__}.ssh_tunnel",
                engine=engine,
            )
            # So we can show the original message
            raise
        except (

View on GitHub (pinned to f4587218dd)

Solutions

Verify connectivity from the Superset host/container: psql/mysql/nc to the same host:port, same credentials.
Correct the sqlalchemy_uri (scheme, host, port, db name) and embed any required SSL params.
Install the missing driver for that engine (check requirements/ and the DB engine docs) and restart Superset.
Compare with the OAuth2/SSH exceptions: if the failure is OAuth2-related the create still proceeds — otherwise treat this as a hard connectivity failure.
Check on the database side for host-based auth / IP allowlisting of the Superset host.

Example fix

# before
sqlalchemy_uri: "postgresql://user:pass@db.internal:5432/analytics"
# -> DatabaseConnectionFailedError (DNS/firewall)

# after: reachable host + ssl
sqlalchemy_uri: "postgresql://user:pass@db.prod.example.com:5432/analytics?sslmode=require"

Defensive patterns

Strategy: try-catch

Validate before calling

from sqlalchemy.engine import make_url

def uri_is_wellformed(uri: str) -> bool:
    try:
        make_url(uri)
        return bool(make_url(uri).get_backend_name())
    except Exception:
        return False

Try / catch

from superset.commands.database.exceptions import DatabaseConnectionFailedError

try:
    CreateDatabaseCommand(data).run()
except DatabaseConnectionFailedError:
    # show connection diagnostics UI: host/port/credentials/driver hints
    ...

Prevention

Run POST /api/v1/database/test_connection before the create call.
Verify network reachability and driver availability from the Superset container, not your laptop.
Encode TLS requirements in the URI (e.g. ?sslmode=require) up front.

When it happens

Trigger: POST /api/v1/database/ (or /test_connection) where the sqlalchemy_uri points to an unreachable host, wrong port, non-existent database, wrong username/password, or the DBAPI driver for that engine is not installed in the Superset environment.

Common situations: Typos in host/port; credentials rotated out-of-band; the database only reachable from a different network segment (Superset container cannot resolve/resolve internal DNS); missing drivers like psycopg2, pymysql, or cx_Oracle; TLS/SSL requirements not encoded in the URI.

Related errors

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