Show friendly error when Superset unable to connect to backing database

[georgeteena]

Hi @dosu,

How to wrap the actual error in a friendly message when connection to backing database fails?

Current error in charts:

DB engine Error
(psycopg2.OperationalError) connection to server at "database host" (xxx.yy.xxx.yyy), port xxxx failed: FATAL: password authentication failed for user "xxxx-yyyy-sssss-hhhh"

(Background on this error at: https://sqlalche.me/e/14/e3q8)
This may be triggered by:
Issue 1011 - Superset encountered an unexpected error. 

Please reach out to the Chart Owner for assistance.

I would like to wrap this error into a Network error or Bad Gateway error without disclosing the database host/port/user details.

[dosubot[bot]]

Superset already has a built-in mechanism for transforming raw database errors into user-friendly messages — it's the custom_errors dictionary in each database engine spec. For PostgreSQL specifically, patterns for connection failures (invalid password, host down, port closed) are already defined in superset/db_engine_specs/postgres.py [1].

Here's how the system works and how you can customize it:

How it works: When a chart query fails, BaseEngineSpec.extract_errors() matches the raw error message against regex patterns in custom_errors. If a pattern matches, it returns a structured SupersetError with a sanitized, user-friendly message instead of the raw driver output [2].

Why you might still see raw errors: If the specific error string from your psycopg2 driver doesn't match any of the existing regex patterns, the system falls back to GENERIC_DB_ENGINE_ERROR, which may still expose raw details [3].

To wrap connection errors in a friendlier message, you can extend the PostgreSQL engine spec's custom_errors dictionary in superset/db_engine_specs/postgres.py:

# Add a pattern that catches the "password authentication failed" error
CONNECTION_INVALID_PASSWORD_REGEX = re.compile(
    r'connection to server .+ failed: FATAL:\s+password authentication failed for user'
)

# Then in the custom_errors dict:
custom_errors = {
    CONNECTION_INVALID_PASSWORD_REGEX: (
        __("Unable to connect to the database. Please contact your administrator."),
        SupersetErrorType.CONNECTION_INVALID_PASSWORD_ERROR,
        {"invalid": ["password"]},
    ),
    # ... other patterns
}

This approach lets you:

• Hide host/port/user details from end users
• Show a generic "network error" or "unable to connect" message
• Still log the full error server-side for debugging

If you want a broader catch-all for any connection failure (not just password errors), you could add a more general regex pattern that matches the psycopg2.OperationalError message format and maps it to a generic friendly message.

Note that Superset also has password masking for SQLAlchemy URIs that appear in error metadata [4], but that's separate from the chart-facing error messages you're asking about.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[dosubot[bot]]

Yes, you can do this from superset_config.py using FLASK_APP_MUTATOR — though not by directly overriding the engine spec's custom_errors patterns (those are hardcoded class attributes and not exposed as a config variable) [1].

Here's the approach using FLASK_APP_MUTATOR to register a custom Flask error handler:

# superset_config.py

def FLASK_APP_MUTATOR(app):
    from flask import jsonify
    from psycopg2 import OperationalError

    @app.errorhandler(Exception)
    def handle_db_connection_error(error):
        # Intercept database connection errors and return a sanitized message
        error_str = str(error)
        if "OperationalError" in error_str or "connection to server" in error_str:
            return jsonify({
                "errors": [{
                    "message": "Unable to connect to the database. Please contact your administrator.",
                    "error_type": "CONNECTION_DATABASE_ERROR",
                    "level": "error",
                }]
            }), 502
        # Let other errors pass through to default handling
        raise error

However, chart query errors go through a different path (the query execution pipeline) and may not be caught by Flask error handlers at the HTTP level. A more targeted approach is to monkey-patch the PostgreSQL engine spec's custom_errors from within FLASK_APP_MUTATOR:

# superset_config.py
import re

def FLASK_APP_MUTATOR(app):
    from superset.db_engine_specs.postgres import PostgresEngineSpec
    from superset.errors import SupersetErrorType

    # Add/override a catch-all pattern for connection failures
    CONNECTION_FAILED_REGEX = re.compile(
        r"connection to server .+ failed"
    )
    PostgresEngineSpec.custom_errors[CONNECTION_FAILED_REGEX] = (
        "Unable to connect to the database. Please contact your administrator.",
        SupersetErrorType.CONNECTION_DATABASE_ERROR,
        {},
    )

This second approach directly extends the engine spec's error patterns at app startup, so when chart queries fail with a connection error, the raw message gets replaced with your friendly text [2] [3].

You can also set SHOW_STACKTRACE = False [4] to ensure stack traces aren't leaked to users.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[georgeteena]

The second approach wasn't successful in masking the raw error. on a dashboard level, is it possible apply some config NOT to show the raw errors?
@dosu

[dosubot[bot]]

Unfortunately, there is no built-in superset_config.py setting that suppresses raw database error messages on dashboards. The SHOW_STACKTRACE = False setting (which is the default) only hides the Python traceback — the raw database error text (host, port, user details) still gets passed through to users [1] .

The reason the monkey-patching approach may not have worked is that the error message likely doesn't match the regex pattern exactly, or the error is being surfaced through a different code path (e.g., error_msg_from_exception() extracts the full text before extract_errors() can intercept it) [2].

What you can try via superset_config.py:

Use FLASK_APP_MUTATOR to patch the error_msg_from_exception utility itself, which is the function that extracts and returns the raw error text to the frontend:

# superset_config.py
import re

def FLASK_APP_MUTATOR(app):
    from superset import utils
    from superset.utils import core as utils_core

    _original_error_msg = utils_core.error_msg_from_exception

    def sanitized_error_msg(ex):
        msg = _original_error_msg(ex)
        # If it looks like a connection error, replace with generic message
        if re.search(r"(connection to server|OperationalError|password authentication failed)", str(msg), re.IGNORECASE):
            return "Unable to connect to the database. Please reach out to the Chart Owner for assistance."
        return msg

    utils_core.error_msg_from_exception = sanitized_error_msg

This patches the function at the point where error messages are extracted, before they're sent to the frontend [2]. However, be aware that this approach has a caveat: depending on the import order, some modules may have already imported the original function reference directly.

Bottom line: Superset doesn't currently offer a simple on/off config to hide raw DB errors from dashboards. Achieving this cleanly would require either:

1. The monkey-patching approach above (best effort from config)
2. A custom frontend build that overrides the DatabaseErrorMessage component to display only a generic message [3] [4]
3. A code change to the Superset source to add a dedicated config option for this

This might be worth raising as a feature request — a config like SANITIZE_DB_ERRORS = True would be a useful security option for production deployments.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[georgeteena]

@dosu The friendly error is indeed displayed when the slice's dataset is not virtual. For virtual datasets, I still see the raw errors.

[dosubot[bot]]

That's an interesting finding. According to the code, virtual and physical datasets go through the same error handling path in SqlaTable.query() — both use db_engine_spec.extract_errors(ex) and error_msg_from_exception(ex) identically [1]. There's no conditional logic that treats them differently for error handling.

The likely reason your monkey-patch works for physical datasets but not virtual ones is an import ordering issue. The function error_msg_from_exception may have already been imported by reference (e.g., from superset.utils.core import error_msg_from_exception) in certain modules before FLASK_APP_MUTATOR runs, so your patched version isn't used in all code paths.

To address this, try patching at multiple levels in your FLASK_APP_MUTATOR:

def FLASK_APP_MUTATOR(app):
    import re
    from superset.utils import core as utils_core
    from superset.connectors.sqla import models as sqla_models

    _original = utils_core.error_msg_from_exception

    def sanitized_error_msg(ex):
        msg = _original(ex)
        if re.search(
            r"(connection to server|OperationalError|password authentication failed)",
            str(msg), re.IGNORECASE
        ):
            return "Unable to connect to the database. Please reach out to the Chart Owner for assistance."
        return msg

    # Patch at the module level AND anywhere it's been imported directly
    utils_core.error_msg_from_exception = sanitized_error_msg

    # Also patch it where it's used in the connectors module
    if hasattr(sqla_models, 'utils'):
        sqla_models.utils.error_msg_from_exception = sanitized_error_msg

Alternatively, a more reliable approach is to patch the extract_errors method on the engine spec class itself, since that's called by reference on the class:

def FLASK_APP_MUTATOR(app):
    import re
    from superset.db_engine_specs.postgres import PostgresEngineSpec

    _original_extract = PostgresEngineSpec.extract_errors

    @classmethod
    def sanitized_extract_errors(cls, ex):
        from superset.errors import SupersetError, SupersetErrorType, ErrorLevel
        msg = str(ex)
        if re.search(r"(connection to server|OperationalError|password authentication)", msg, re.IGNORECASE):
            return [SupersetError(
                message="Unable to connect to the database. Please reach out to the Chart Owner for assistance.",
                error_type=SupersetErrorType.CONNECTION_DATABASE_ERROR,
                level=ErrorLevel.ERROR,
                extra={"engine_name": "PostgreSQL"},
            )]
        return _original_extract.__func__(cls, ex)

    PostgresEngineSpec.extract_errors = sanitized_extract_errors

This patches the class method directly, so regardless of how it's imported or called, both virtual and physical datasets will hit the patched version.

Could you share the exact raw error you're seeing for the virtual dataset case? It might reveal whether the error is coming through a slightly different exception type or code path that I can help you target more precisely.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.