apache/superset · error · DatabaseOfflineError

Database is offline.

Error message

Database is offline.

What it means

DatabaseOfflineError (HTTP 422) is raised by the database connection-test/validate command when the engine spec's connectivity check completes without raising but reports the database as not alive (`if not alive:` in superset/commands/database/validate.py). It means Superset reached its own validation logic, built a URL, and the resulting connection was determined to be down. It is distinct from DatabaseTestConnectionFailedError, which is raised earlier when the connection attempt itself throws an exception.

Solutions

1. Verify the database server is running and reachable from the Superset host (e.g., `nc -vz <host> <port>` or `psql`/client CLI from the same container).
2. Re-check the connection parameters in the database settings (hostname, port, username, password, database name) and use the 'Test Connection' button after fixing.
3. If a network policy or Docker network isolation blocks egress, open the route from the Superset container/pod to the database host and port.
4. If the engine is a paused/suspended warehouse (Snowflake serverless, BigQuery reservations, etc.), wake it up or adjust keep-alive settings, then retest.

# Pre-flight reachability check before saving/testing a Database
from superset.commands.database.validate import DatabaseConnectionCommand

def database_reachable(db_connection_params: dict) -> bool:
    import socket
    host, port = db_connection_params["host"], db_connection_params.get("port")
    if not host or port is None:
        return False
    with socket.socket(socket.AF_INET) as s:
        s.settimeout(3)
        return s.connect_ex((host, int(port))) == 0

from superset.commands.database.exceptions import (
    DatabaseOfflineError, DatabaseTestConnectionFailedError,
)
try:
    DatabaseConnectionCommand(...).run()
except DatabaseOfflineError:
    # 422: engine reported not-alive -> surface 'server down/unreachable', do not retry immediately
    show_operator_message("Database server is offline or unreachable")
except DatabaseTestConnectionFailedError as ex:
    # carries extracted engine errors with status 400
    show_engine_errors(ex.errors[0].message if ex.errors else str(ex))

When it happens

Trigger: Calling the database test-connection endpoint (POST to the database REST API with 'Test Connection' / the validate command) against a database whose server is stopped, unreachable on the network, or whose `db_engine_spec.test_connection` returns alive=False. Also triggered when a saved database entry references a host/port that has since been decommissioned.

Common situations: DB server restarted or down for maintenance; firewall/VPC rules blocking the port between Superset and the database; wrong host/port in the SQLAlchemy URI; the database engine was paused (e.g., serverless warehouse suspended); DNS name no longer resolves. This appears frequently in CI where no real database is available.

Related errors

• Database not found.
• The database was not found.
• A soft-deleted dataset (uuid %(uuid)s) already references…
• An error occurred while accessing the value.
• An error occurred while creating the value.

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

Appendix: source

Thrown at superset/commands/database/validate.py:164

                    and database.db_engine_spec.needs_oauth2(ex)
                ):
                    return

                url = make_url_safe(sqlalchemy_uri)
                context = {
                    "hostname": url.host,
                    "password": url.password,
                    "port": url.port,
                    "username": url.username,
                    "database": url.database,
                }
                errors = database.db_engine_spec.extract_errors(
                    ex, context, database_name=database.unique_name
                )
                raise DatabaseTestConnectionFailedError(errors, status=400) from ex

        if not alive:
            raise DatabaseOfflineError(
                SupersetError(
                    message=__("Database is offline."),
                    error_type=SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
                    level=ErrorLevel.ERROR,
                ),
            )

    def _load_model(self) -> None:
        """Load the existing database model if updating."""
        if (database_id := self._properties.get("id")) is not None:
            self._model = DatabaseDAO.find_by_id(database_id)

    def _get_database_name_error(self) -> Optional[SupersetError]:
        """Check for duplicate database name and return error if found."""
        database_id = self._properties.get("id")

        if database_name := self._properties.get("database_name"):
            is_unique = (

View on GitHub (pinned to f4587218dd)