apache/superset · error · DatabaseCreateFailedError

Database could not be created.

Error message

Database could not be created.

What it means

DatabaseCreateFailedError raised in CreateDatabaseCommand.run (create.py:118) from the except (DatabaseInvalidError, Exception) block around _create_database() and add_permissions(database). This is the terminal wrap for anything that goes wrong after the test connection succeeded — model-level validation failures, SSH tunnel errors, SQLAlchemy persistence problems in the metadata DB, or permission-sync errors. The @transaction decorator's on_error also reraises into this class.

Source

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

            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 (
            DatabaseInvalidError,
            Exception,
        ) as ex:
            event_logger.log_with_context(
                action=f"db_creation_failed.{ex.__class__.__name__}",
                engine=engine,
            )
            raise DatabaseCreateFailedError() from ex

        return database

    def validate(self) -> None:
        exceptions: list[ValidationError] = []

        sqlalchemy_uri: Optional[str] = self._properties.get("sqlalchemy_uri")
        if not sqlalchemy_uri:
            exceptions.append(DatabaseRequiredFieldValidationError("sqlalchemy_uri"))

        database_name: Optional[str] = self._properties.get("database_name")
        if not database_name:
            exceptions.append(DatabaseRequiredFieldValidationError("database_name"))
        else:
            if not DatabaseDAO.validate_uniqueness(database_name):
                exceptions.append(DatabaseExistsValidationError())

        if exceptions:

View on GitHub (pinned to f4587218dd)

Solutions

1. Read __cause__ / server logs: db_creation_failed.<ExceptionName> is logged with context via event_logger and the original exception is chained.
2. Ensure database_name is present and unique — a duplicate name fails at persist time.
3. If using SSH tunneling, verify SSH_TUNNELING config, the tunnel credentials, and that SSHTunnel* errors are the real cause.
4. Fix any validate()-stage issues first (all required fields present) before retrying the POST.

def create_payload_complete(data: dict) -> bool:
    return all(data.get(f) for f in ("database_name", "sqlalchemy_uri"))

from superset.commands.database.exceptions import DatabaseCreateFailedError

try:
    db = CreateDatabaseCommand(data).run()
except DatabaseCreateFailedError as ex:
    cause = type(ex.__cause__).__name__ if ex.__cause__ else "?"
    log.error("create failed, cause=%s", cause)  # SSH tunnel / validation / metadata DB
    raise

When it happens

Trigger: POST /api/v1/database/ where the payload passes connection testing but fails during persist: e.g. DatabaseInvalidError from validate() (missing database_name), SSHTunnel* errors raised while opening the tunnel, unique-constraint violation on database_name, or metadata DB errors during INSERT.

Common situations: Payload missing database_name (validation error collected earlier and surfaced during create); SSH tunnel settings (server, key) misconfigured; asynchronous SSH tunnel setup failing; duplicate database name; metadata DB constraint issues.

Related errors

• Field is required
• Connection failed, please check your connection settings
• SSH Tunneling is not enabled
• Annotation layer parameters are invalid.
• Error: %(error)s

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