apache/druid · error · IllegalStateException

JDBC driver JAR files missing in the classpath

Error message

JDBC driver JAR files missing in the classpath

What it means

JdbcDataFetcher.runWithMissingJdbcJarHandler() wraps execution of JDBC lookups. When the JDBC driver reports 'No suitable driver found' (UnableToObtainConnectionException), it rethrows as an ISE saying the driver JARs are missing from the classpath — a clearer message for the standard case of an unloaded JDBC driver.

Source

Thrown at extensions-core/lookups-cached-single/src/main/java/org/apache/druid/server/lookup/jdbc/JdbcDataFetcher.java:257

                    }
                    catch (SQLException e) {
                      // at least try to log it so we don't swallow exceptions
                      LOGGER.error(e, "Unable to reset connection read-only state");
                    }
                  }
                }
            )
    );
  }

  private <T> T runWithMissingJdbcJarHandler(Supplier<T> supplier)
  {
    try {
      return supplier.get();
    }
    catch (UnableToObtainConnectionException e) {
      if (e.getMessage().contains("No suitable driver found")) {
        throw new ISE(
            e,
            "JDBC driver JAR files missing in the classpath"
        );
      } else {
        throw e;
      }
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add the JDBC driver JAR to extensions/ and load the corresponding extension (e.g. mysql-metadata-storage)
2. Ensure druid.extensions.loadList includes the extension providing the driver
3. Verify driver compatibility with the Java version and JDBC URL (jdbc:mysql: vs jdbc:postgresql:)

Example fix

// before (no extension loaded)
druid.extensions.loadList=["druid-lookups-cached-single"]
// after
druid.extensions.loadList=["druid-lookups-cached-single", "mysql-metadata-storage"]

try { Class.forName("com.mysql.cj.jdbc.Driver"); } catch (ClassNotFoundException e) { throw new IllegalStateException("MySQL driver not on classpath; install extension"); }

try { return fetcher.fetch(); } catch (ISE e) { if (e.getMessage().contains("JDBC driver JAR files missing")) { throw new ConfigurationException("Load the JDBC driver extension before using JDBC lookups"); } throw e; }

When it happens

Trigger: Using a JDBC-based lookup (JdbcDataFetcher) without the corresponding JDBC driver JAR loaded as a Druid extension, so DriverManager cannot find a driver for the JDBC URL.

Common situations: Configuring a JDBC lookup but forgetting to load the mysql-metadata-storage or postgresql extension; driver JAR present but not on the classpath of the task/router process; driver registration blocked by classloader isolation.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• JDBC driver JAR files missing from extensions/druid-lookups-
• Could not find %s on the classpath. The MySQL Connector libr
• Failed to find MySQL driver class. Please check the MySQL co
• Failed to find MariaDB driver class. Please check the MariaD
• Cannot load JDBC driver class '<driverClassName>'

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