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.

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)

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.
• Error: %(error)s
• Field is required
• Connection failed, please check your connection settings

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