apache/druid · critical · SQLException

Cannot load JDBC driver class '<driverClassName>'

Error message

Cannot load JDBC driver class '<driverClassName>'

What it means

BasicDataSourceExt.createConnectionFactory attempts to load the configured JDBC driver class via the context classloader. If Class.forName/driver loading throws, it wraps the cause in SQLException('Cannot load JDBC driver class <driverClassName>'). This means the driver jar is missing or the class name is wrong.

Source

Thrown at server/src/main/java/org/apache/druid/metadata/BasicDataSourceExt.java:138

          try {
            if (getDriverClassLoader() == null) {
              driverFromCCL = Class.forName(getDriverClassName());
            } else {
              driverFromCCL = Class.forName(
                  getDriverClassName(), true, getDriverClassLoader());
            }
          }
          catch (ClassNotFoundException cnfe) {
            driverFromCCL = Thread.currentThread(
            ).getContextClassLoader().loadClass(
                getDriverClassName());
          }
        }
        catch (Exception t) {
          String message = "Cannot load JDBC driver class '" +
                           getDriverClassName() + "'";
          LOGGER.error(t, message);
          throw new SQLException(message, t);
        }
      }

      try {
        if (driverFromCCL == null) {
          driverToUse = DriverManager.getDriver(getUrl());
        } else {
          // Usage of DriverManager is not possible, as it does not
          // respect the ContextClassLoader
          // N.B. This cast may cause ClassCastException which is handled below
          driverToUse = (Driver) driverFromCCL.newInstance();
          if (!driverToUse.acceptsURL(getUrl())) {
            throw new SQLException("No suitable driver", "08001");
          }
        }
      }
      catch (Exception t) {
        String message = "Cannot create JDBC driver of class '" +

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add the JDBC driver extension to druid.extensions.loadList (e.g. druid-postgresql, mysql-metadata-storage) so the driver jar is on the classpath
2. Verify druid.metadata.storage.connector.driverClassName matches the actual driver class in the bundled jar
3. Check the logged root cause (ClassNotFoundException vs linkage/error) and align the driver version with the database server

Example fix

// before
druid.extensions.loadList=[]
druid.metadata.storage.connector.driverClassName=com.mysql.cj.jdbc.Driver
// after
druid.extensions.loadList=["druid-mysql-metadata-storage"]
druid.metadata.storage.connector.driverClassName=com.mysql.cj.jdbc.Driver

try { Class.forName(driverClassName, true, Thread.currentThread().getContextClassLoader()); } catch (ClassNotFoundException e) { throw new IllegalStateException("JDBC driver not on classpath: " + driverClassName); }

try { dataSource.getConnection(); } catch (SQLException e) { if (e.getMessage() != null && e.getMessage().startsWith("Cannot load JDBC driver class")) { log.error("JDBC driver missing; check druid.extensions.loadList and driver jar"); } throw e; }

When it happens

Trigger: Metadata storage configured with a driverClassName that cannot be instantiated/loaded: wrong class name, missing JDBC driver jar on the classpath, or driver static initialization failure (e.g. ClassNotFoundException, NoClassDefFoundError, driver version incompatibility).

Common situations: Forgetting to bundle the PostgreSQL/MySQL JDBC driver extension in the Druid extensions load list; typo in driver class name (e.g. org.postgresql.Driver misspelled); driver jar version conflicts after upgrade.

Related errors

• JDBC driver JAR files missing from extensions/druid-lookups-
• JDBC driver JAR files missing in the classpath
• Failed to find MySQL driver class. Please check the MySQL co
• Failed to find MariaDB driver class. Please check the MariaD
• connectionProperties is null

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/7217ae88cfa4cbaf. Report an issue: GitHub.