{"record":{"id":"4a1b6b1dcdc4b87a","repo":"apache/superset","slug":"connection-failed-please-check-your-connection-se-4a1b6b","errorCode":null,"errorMessage":"Connection failed, please check your connection settings","messagePattern":"Connection failed, please check your connection settings","errorType":"exception","errorClass":"DatabaseConnectionFailedError","httpStatus":500,"severity":"error","filePath":"superset/commands/database/sync_permissions.py","lineNumber":125,"sourceCode":"        if not self.username or not (\n            user := security_manager.get_user_by_username(self.username)\n        ):\n            raise UserNotFoundInSessionError()\n        self._user_id = user.id\n\n        with self.db_connection.get_sqla_engine() as engine:\n            try:\n                alive = ping(engine)\n            except Exception as err:\n                if (\n                    self.db_connection.is_oauth2_enabled()\n                    and self.db_connection.db_engine_spec.needs_oauth2(err)\n                ):\n                    raise MissingOAuth2TokenError() from err\n                raise DatabaseConnectionFailedError() from err\n\n        if not alive:\n            raise DatabaseConnectionFailedError()\n\n    def run(self) -> None:\n        \"\"\"\n        Triggers the perm sync in sync or async mode.\n        \"\"\"\n        self.validate()\n        if self.async_mode:\n            sync_database_permissions_task.delay(\n                self.db_connection_id, self._user_id, self.old_db_connection_name\n            )\n            return\n\n        self.sync_database_permissions()\n\n    @transaction(\n        on_error=partial(on_error, reraise=DatabaseConnectionSyncPermissionsError)\n    )\n    def sync_database_permissions(self) -> None:","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/commands/database/sync_permissions.py#L107-L143","documentation":"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__.","triggerScenarios":"Wrong host/port/credentials in the connection settings; database server down or unreachable from Superset; firewall/DNS issues; the SQLAlchemy URL parameters are invalid.","commonSituations":"Expired DB passwords, VPN/network changes, database migrated to a new host, TLS settings mismatch between Superset and the DB server.","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)"],"exampleFix":"// before\n conn = sqlalchemy.create_engine(\"postgresql://u:p@db:5432/x\")\n\n// after\n conn = sqlalchemy.create_engine(\"postgresql://u:p@db.example.com:5432/x\")  # correct host","handlingStrategy":"retry","validationCode":"from superset.utils.core import ping\n\nwith db_conn.get_sqla_engine() as engine:\n    if not ping(engine):\n        raise ConnectionError(\"database unreachable; fix connection settings\")","typeGuard":null,"tryCatchPattern":"try:\n    cmd.run()\nexcept DatabaseConnectionFailedError as e:\n    cause = e.__cause__  # driver-level detail\n    # fix settings or retry with backoff for transient faults\n    ...","preventionTips":["Run 'Test Connection' after any credential/network change","Wrap syncs with bounded retry for transient outages"],"tags":["database","network","connection"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}