apache/druid · critical · SQLException

Cannot create JDBC driver of class '<driverClassName>' for c

Error message

Cannot create JDBC driver of class '<driverClassName>' for connect URL '<url>'

What it means

BasicDataSourceExt.createConnectionFactory catches any Exception raised while resolving the driver or probing the URL and rethrows it as SQLException('Cannot create JDBC driver of class <driverClassName> for connect URL <url>'), preserving the original cause. It is a generic wrapper for driver creation failures beyond class loading itself (e.g. the ClassCastException noted in the code, or acceptsURL throwing).

Source

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

      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 '" +
                         (getDriverClassName() != null ? getDriverClassName() : "") +
                         "' for connect URL '" + getUrl() + "'";
        LOGGER.error(t, message);
        throw new SQLException(message, t);
      }
    }

    if (driverToUse == null) {
      throw new RE("Failed to find the DB Driver");
    }

    final Driver finalDriverToUse = driverToUse;

    return () -> {
      String user = connectorConfig.getUser();
      if (user != null) {
        connectionProperties.put("user", user);
      } else {
        log("DBCP DataSource configured without a 'username'");
      }

      // Note: This is the main point of this class where we are getting fresh password before setting up

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Check the root cause in the logged stack trace and fix the specific underlying error
  2. Set driverClassName to a class implementing java.sql.Driver (e.g. org.postgresql.Driver, com.mysql.cj.jdbc.Driver)
  3. Remove conflicting duplicate driver jars from the classpath

Example fix

// before
druid.metadata.storage.connector.driverClassName=org.postgresql.ds.PGSimpleDataSource
// after
druid.metadata.storage.connector.driverClassName=org.postgresql.Driver
Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> c = Class.forName(driverClassName); if (!java.sql.Driver.class.isAssignableFrom(c)) { throw new IllegalStateException(driverClassName + " does not implement java.sql.Driver"); }

Try / catch

try { dataSource.getConnection(); } catch (SQLException e) { if (e.getMessage() != null && e.getMessage().startsWith("Cannot create JDBC driver of class")) { log.error(e.getCause(), "Driver creation failed; check cause"); } throw e; }

Prevention

When it happens

Trigger: createConnectionFactory where the driverFromCCL.newInstance() cast to Driver fails (ClassCastException — the class loaded is not a java.sql.Driver), or any other exception in the driver/URL resolution block.

Common situations: driverClassName pointing at a class that is not a JDBC Driver (e.g. a DataSource class or wrong class); classloader conflicts returning a different class than expected; driver initialization throwing in its constructor.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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