// troubleshooting guide · apache superset

Superset Could Not Load Database Driver

Status
Workaround available
platforms:
Self-hosted, Docker, Kubernetes
updated:
November 16, 2026
reports:
3
Method
how we research
Share

RUNBOOK · apache-superset/could-not-load-database-driver4 FIXES

// quick answer

'Could not load database driver' means the Python driver for that database is not installed in the Superset environment. In Docker, add it to docker/requirements-local.txt and rebuild, rather than pip installing into a running container.

Most likely fix: Add the driver in Docker

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Add the driver in Docker

    1. 01Add the package to ./docker/requirements-local.txt
    2. 02Run docker compose build --force-rm
    3. 03Run docker compose up
    Did this fix it?
  2. FIX 2Install in a custom image

    1. 01Create a Dockerfile FROM apache/superset:<version>
    2. 02Run pip install <driver> in it
    3. 03Deploy that image instead of the stock one
    Did this fix it?
  3. FIX 3Verify the install

    1. 01docker exec into the container
    2. 02Run pip freeze | grep <driver>
    Did this fix it?
  4. FIX 4Pin compatible versions

    1. 01Check the driver's supported SQLAlchemy version
    2. 02Pin the driver version in requirements-local.txt if the latest conflicts
    Did this fix it?

SANDBOX · apache-superset RUNS IN YOUR BROWSER

Try it: browse a sample shop and watch visitors, funnels and live data arrive

A hands-on Apache Superset-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

Connecting a database fails with 'ERROR: Could not load database driver: <Name>EngineSpec'.

Why it happens

  • C-01Driver package not installed (e.g. mysqlclient, snowflake-sqlalchemy, trino)
  • C-02Installed in a running container that was later recreated
  • C-03Driver version incompatible with Superset's SQLAlchemy version
  • C-04Wrong SQLAlchemy URI prefix

// this guide also covers

  • superset could not load database driver
  • superset mysql driver
  • superset add database driver docker
  • superset requirements-local.txt

Still not working?

If Apache Superset keeps failing, you're not alone. See every Apache Superset problem users report or the alternatives people switch to.

Done fighting Apache Superset? Our small team builds your own Apache Superset alternative, or any software you need: web, mobile, games, desktop. Price agreed together.

Talk to us

Watch Apache Superset Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other Apache Superset errors

All 14 Apache Superset errors and fixes →