feat(db): custom database error messages #34674

DamianPendrak · 2025-08-13T14:45:08Z

SUMMARY

Introduce CUSTOM_DATABASE_ERRORS in the config to replace raw database exceptions with a custom message and optional documentation links.

custom_doc_links - contains links that will show after the error message
show_issue_info - if set to False, hides the "See more" button that contains the issue code and link to Superset documentation

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Before

After

TESTING INSTRUCTIONS

In SQL Lab, run a query that results in a database error, ex. "SELECT * FROM non_existing_table"
Find a string that will match this error with a regex, ex. "TrinoUserError"
Add the custom errors in the superset/custom_database_errors.py file or add CUSTOM_DATABASE_ERRORS to superset_config.py or other config file with this structure:

CUSTOM_DATABASE_ERRORS = {
    "examples": {
        re.compile('permission denied for view'): (
            __(
                'Permission denied'
            ),
            SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
            {
                "custom_doc_links": [
                    {
                        "url": "https://example.com/docs/1",
                        "label": "Check documentation"
                    },
                ],
                "show_issue_info": False,
            }
        )
    },
}

examples - the database connection name.
permission denied for view - part of the original message.

ADDITIONAL INFORMATION

Has associated issue:
Required feature flags:
Changes UI
Includes DB Migration (follow approval process in SIP-59)
- Migration is atomic, supports rollback & is backwards-compatible
- Confirm DB migration upgrade and downgrade tested
- Runtime estimates and downtime expectations provided
Introduces new feature or API
Removes existing feature or API

korbit-ai

Review by Korbit AI

Korbit automatically attempts to detect when you fix issues in new commits.

Category	Issue	Status
	Unclear Icon Purpose for Documentation Link ▹ view	🧠 Not in standard
	Sequential Regex Pattern Matching ▹ view	🧠 Incorrect
	Missing URL Validation ▹ view	🧠 Not in standard
	Unsafe Issue Codes Access ▹ view	🧠 Not in scope

Files scanned

File Path	Reviewed
superset-frontend/src/components/ErrorMessage/CustomDocLink.tsx	✅
superset-frontend/src/components/ErrorMessage/DatabaseErrorMessage.tsx	✅
docs/docs/configuration/databases.mdx	✅
superset/db_engine_specs/base.py	✅
superset/config.py	✅

Explore our documentation to understand the languages and file types we support and the files we ignore.

Check out our docs on how you can make Korbit work best for you and your team.

Loving Korbit!? Share us on LinkedIn Reddit and X

superset-frontend/src/components/ErrorMessage/CustomDocLink.tsx

+  const theme = useTheme();
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer">
+      {label} <Icons.Full iconSize="m" iconColor={theme.colorPrimary} />


superset-frontend/src/components/ErrorMessage/CustomDocLink.tsx

+export const CustomDocLink = ({ url, label }: CustomDocLinkProps) => {
+  const theme = useTheme();
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer">


superset-frontend/src/components/ErrorMessage/DatabaseErrorMessage.tsx

-            <IssueCode {...issueCode} key={issueCode.code} />
-          ))
-          .reduce((prev, curr) => [prev, <br />, curr])}
+        {extra.issue_codes?.flatMap((issueCode, idx, arr) => [


superset/db_engine_specs/base.py

+        for regex, (message, error_type, extra) in [
+            *config_custom_errors.items(),
+            *cls.custom_errors.items(),
+        ]:
            if match := regex.search(raw_message):


codecov · 2025-08-13T14:50:52Z

Codecov Report

❌ Patch coverage is 65.51724% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.85%. Comparing base (7f38405) to head (ad1ee1a).

Files with missing lines	Patch %	Lines
superset/db_engine_specs/databricks.py	0.00%	4 Missing ⚠️
superset/db_engine_specs/base.py	76.92%	1 Missing and 2 partials ⚠️
superset/config.py	50.00%	2 Missing ⚠️
superset/commands/database/validate.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           master   #34674       +/-   ##
===========================================
+ Coverage        0   71.85%   +71.85%     
===========================================
  Files           0      588      +588     
  Lines           0    43534    +43534     
  Branches        0     4708     +4708     
===========================================
+ Hits            0    31280    +31280     
- Misses          0    11023    +11023     
- Partials        0     1231     +1231

Flag	Coverage Δ
hive	`46.26% <51.72%> (?)`
mysql	`70.87% <65.51%> (?)`
postgres	`70.93% <65.51%> (?)`
presto	`49.95% <51.72%> (?)`
python	`71.81% <65.51%> (?)`
sqlite	`70.52% <65.51%> (?)`
unit	`100.00% <ø> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sadpandajoe · 2025-08-14T17:27:25Z

@DamianPendrak so would you need files per database as different databases could have different links and different messages? Would it be helpful to also have a link or a collapsed box that will show the original error?

DamianPendrak · 2025-08-15T10:57:02Z

@sadpandajoe My idea was to separate them based on the regex. But now I see that it might be an issue if there is the same error message from different databases, and you can't separate them using regex. I pushed an update with a changed structure of the CUSTOM_DATABASE_ERRORS so we can separate them by database engine names, and apply them accordingly:

CUSTOM_DATABASE_ERRORS = {
  "trino": {
    re.compile(r"TrinoUserError"): (
        "Custom error message",
        SupersetErrorType.GENERIC_DB_ENGINE_ERROR,
        {
            "custom_doc_links": [
                {
                    "url": "https://example.com/docs",
                    "label": "Check documentation"
                },
            ],
        }
    ),
  },
  "postgres": {}
}

About the original error - there is a similar way to overwrite the error messages in the db engine file in superset/db_engine_specs. Currently, it only shows an issue code and a link to the documentation in a collapsed component. The original error might be useful, but then I think it should be available in both custom error messages (db_engine_specs file and superset_config.py)

sadpandajoe · 2025-08-15T16:23:45Z

@DamianPendrak one other question. If you want to override multiple error messages and you have multiple databases, won't the config file get huge? Wondering if that is fine or not.

DamianPendrak · 2025-08-18T15:58:44Z

@sadpandajoe, good point. The config file could become huge, so it's a good idea to put it into a separate file. I pushed the change that imports the custom errors, but you can still overwrite them in the config file

kgabryje · 2025-08-26T13:12:01Z

superset/custom_database_errors.py

+# Example:
+# CUSTOM_DATABASE_ERRORS = {
+#     "trino": {
+#         re.compile(r'message="(?P<message>[^"]*)"'): (


Could we perhaps make it easier to append a custom message or just the doc links to the original message? I know that this regex does that, but who likes writing regexes 😄

Right, that's probably too advanced example. I added a simpler one that matches with a part of the error message "permission denied for view". The regex is also used in the custom errors in the database engine files, so it keeps the same approach

kgabryje · 2025-08-26T13:13:45Z

superset-frontend/src/components/ErrorMessage/CustomDocLink.tsx

+  const theme = useTheme();
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer">
+      {label} <Icons.Full iconSize="m" iconColor={theme.colorPrimary} />


Nit: I think the icon is not centered vertically with the text. Also, the text's color changes on hover, but icon's color doesn't

kgabryje · 2025-08-26T13:19:23Z

superset/db_engine_specs/base.py

+        config_custom_errors = app.config.get("CUSTOM_DATABASE_ERRORS", {})
+        if not isinstance(config_custom_errors, dict):
+            config_custom_errors = {}
+        db_engine_custom_errors = config_custom_errors.get(cls.engine_name, {})


Should we also check for cls.engine? I tested on sqlite, and when I used sqlite as key in CUSTOM_DATABASE_ERRORS dict, it didn't work because cls.engine_name returns SQLite. Perhaps we could allow for both "human readable" and "normal" engine names?

Done. Works with both now

Vitor-Avila · 2025-08-27T22:30:00Z

hey @DamianPendrak could it be a concern if I have 2 trino connections (maybe with different auth methods each) and I just want to show a custom error message on one of them?

DamianPendrak · 2025-08-29T11:43:43Z

@Vitor-Avila it could be an issue if the error message is the same and cannot be distinguished from another error message using regex. If one of the auth methods returned a different error message, then it can be achieved.

kgabryje

LGTM

kgabryje · 2025-09-02T10:38:00Z

Added hold! label per contributor's request

DamianPendrak · 2025-09-10T17:09:44Z

Thanks @Vitor-Avila for pointing that out. I changed the implementation to match errors with the database unique name instead of the database engine name. It allows users to create more precise custom errors. @kgabryje are you okay with reviewing the changes?

kgabryje · 2025-09-11T08:05:28Z

superset/db_engine_specs/base.py

+            if isinstance(database_errors, dict):
+                db_engine_custom_errors.update(database_errors)

        if not isinstance(db_engine_custom_errors, dict):


Is there any scenario where db_engine_custom_errors is not a dict? We initialize it as dict in line 1343, and then update it only with other dicts

That's right. Removed the unnecessary check

kgabryje · 2025-09-11T08:07:53Z

superset/db_engine_specs/databricks.py

+        if not isinstance(config_custom_errors, dict):
+            config_custom_errors = {}
+
+        db_engine_custom_errors = {}


This part is very similar to base.py. Does it make sense to DRY it?

Good point. Moved it to a method

github-actions · 2025-09-23T14:53:04Z

🎪 Showtime deployed environment on GHA for 55d3b07

• Environment: http://34.219.185.149:8080 (admin/admin)
• Lifetime: 48h auto-cleanup
• Updates: New commits create fresh environments automatically

github-actions · 2025-09-23T15:34:03Z

⚠️ DEPRECATED WORKFLOW ⚠️

@kgabryje This workflow is deprecated! Please use the new Superset Showtime system instead:

Replace "testenv-up" label with "🎪 trigger-start"
Better reliability and easier management
See https://github.com/mistercrunch/superset-showtime for details

Processing your ephemeral environment request here. Action: up. More information on how to use or configure ephemeral environments

github-actions · 2025-09-23T15:46:52Z

@kgabryje Ephemeral environment spinning up at http://44.251.62.68:8080. Credentials are 'admin'/'admin'. Please allow several minutes for bootstrapping and startup.

…upersetError

…age when custom message is empty

pull-request-size bot added the size/L label Aug 13, 2025

github-actions bot added the doc Namespace | Anything related to documentation label Aug 13, 2025

dosubot bot added change:backend Requires changing the backend change:frontend Requires changing the frontend labels Aug 13, 2025

korbit-ai bot reviewed Aug 13, 2025

View reviewed changes

yousoph requested a review from geido August 13, 2025 18:46

DamianPendrak force-pushed the custom-db-error-messages branch from 10b4bb6 to d479656 Compare August 18, 2025 12:15

pull-request-size bot added size/XL size/L and removed size/L size/XL labels Aug 18, 2025

geido requested a review from Vitor-Avila August 18, 2025 17:48

kgabryje reviewed Aug 26, 2025

View reviewed changes

pull-request-size bot added size/XL and removed size/L labels Aug 28, 2025

kgabryje approved these changes Sep 2, 2025

View reviewed changes

kgabryje added the hold! On hold label Sep 2, 2025

kgabryje reviewed Sep 11, 2025

View reviewed changes

kgabryje added the testenv-up label Sep 23, 2025

DamianPendrak added 19 commits September 24, 2025 22:12

Add custom database error messages

7d8a314

Add tests, documentation, and examples

6440a4d

Add frontend tests

dcf51d8

Improve custom doc links validation; Add test for wrong doc links value

1bd8ac8

Fix console error caused by missing key in a list

5e23fac

Change the custom doc links key

cee606a

Fix eslint

ae01a18

Add db engine specific custom error messages

4b5224a

Move the custom database errors to a separate config file

e2ff5ee

Improve custom error config import safety and test coverage

8d81954

Add test to improve coverage

272815f

Refactor extract_errors tests to use a helper function for expected S…

51631d7

…upersetError

Add more basic regex as an example

32678a1

Improve CustomDocLink component

8e6abc7

Match errors with engine_name and engine; Don't replace original mess…

2e09656

…age when custom message is empty

Add database_name parameter to extract_errors

3a15db6

Change custom error matching from engine to database name

ddef424

Apply PR feedback

6766f4e

Temporary custom errors for testing

ad1ee1a

DamianPendrak force-pushed the custom-db-error-messages branch from 55d3b07 to ad1ee1a Compare September 24, 2025 20:13

feat(db): custom database error messages #34674

Are you sure you want to change the base?

feat(db): custom database error messages #34674

Conversation

DamianPendrak commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SUMMARY

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Before

After

TESTING INSTRUCTIONS

ADDITIONAL INFORMATION

Uh oh!

korbit-ai bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review by Korbit AI

Korbit automatically attempts to detect when you fix issues in new commits.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

codecov bot commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sadpandajoe commented Aug 14, 2025

Uh oh!

DamianPendrak commented Aug 15, 2025

Uh oh!

sadpandajoe commented Aug 15, 2025

Uh oh!

DamianPendrak commented Aug 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Vitor-Avila commented Aug 27, 2025

Uh oh!

DamianPendrak commented Aug 29, 2025

Uh oh!

kgabryje left a comment

Choose a reason for hiding this comment

Uh oh!

kgabryje commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DamianPendrak commented Sep 10, 2025

Uh oh!

kgabryje Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 23, 2025

Uh oh!

github-actions bot commented Sep 23, 2025

Uh oh!

github-actions bot commented Sep 23, 2025

Uh oh!

Uh oh!

DamianPendrak commented Aug 13, 2025 •

edited

Loading

korbit-ai bot left a comment •

edited

Loading

codecov bot commented Aug 13, 2025 •

edited

Loading

kgabryje commented Sep 2, 2025 •

edited

Loading

kgabryje Sep 11, 2025 •

edited

Loading