apache/druid · error · IllegalStateException

JDBC driver JAR files missing from extensions/druid-lookups-

Error message

JDBC driver JAR files missing from extensions/druid-lookups-cached-global directory

What it means

JdbcCacheGenerator opens a JDBC connection to refresh the lookup cache. When the connection attempt fails because no suitable JDBC driver was registered (UnableToObtainConnectionException mentioning 'No suitable driver'), the generator translates it into this explicit ISE, since Druid does not bundle JDBC drivers for lookups.

Source

Thrown at extensions-core/lookups-cached-global/src/main/java/org/apache/druid/server/lookup/namespace/JdbcCacheGenerator.java:86

      final JdbcExtractionNamespace namespace,
      final CacheScheduler.EntryImpl<JdbcExtractionNamespace> entryId,
      final String lastVersion,
      final CacheHandler cache
  )
  {
    final long lastCheck = lastVersion == null ? JodaUtils.MIN_INSTANT : Long.parseLong(lastVersion);
    final Long lastDBUpdate;
    final long dbQueryStart;

    try {
      lastDBUpdate = lastUpdates(entryId, namespace);
      if (lastDBUpdate != null && lastDBUpdate <= lastCheck) {
        return null;
      }
    }
    catch (UnableToObtainConnectionException e) {
      if (e.getMessage().contains(NO_SUITABLE_DRIVER_FOUND_ERROR)) {
        throw new ISE(e, JDBC_DRIVER_JAR_FILES_MISSING_ERROR);
      } else {
        throw e;
      }
    }
    dbQueryStart = System.currentTimeMillis();

    LOG.debug("Updating %s", entryId);

    final String newVersion;
    if (lastDBUpdate != null) {
      newVersion = lastDBUpdate.toString();
    } else {
      newVersion = StringUtils.format("%d", dbQueryStart);
    }

    final long startNs = System.nanoTime();
    try (
        Handle handle = getHandle(entryId, namespace);

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Copy the JDBC driver JAR into extensions/druid-lookups-cached-global/ and restart the Druid process.
2. Verify the jdbcDriverClass name in the JDBC lookup config matches the driver (e.g. com.mysql.cj.jdbc.Driver).
3. Confirm the extension directory is included in druid.extensions.loadList / the runtime classpath.

Example fix

# before
ls extensions/druid-lookups-cached-global/   # no mysql-connector jar
# after
cp mysql-connector-j-8.x.jar extensions/druid-lookups-cached-global/

// before scheduling a JDBC lookup
File extDir = new File("extensions/druid-lookups-cached-global");
boolean driverPresent = extDir.exists() && Arrays.stream(extDir.listFiles()).anyMatch(f -> f.getName().matches("(mysql|postgresql|mariadb).*\\.jar"));

try { scheduler.schedule(jdbcNamespace); } catch (IllegalStateException e) { if (e.getMessage().contains("JDBC driver JAR files missing")) { /* deploy driver JAR and retry */ } else { throw e; } }

When it happens

Trigger: generateCache() connecting to the configured JDBC lookup when the driver class/JAR is not on the classpath, so DriverManager cannot find a suitable driver.

Common situations: Forgetting to place the JDBC driver JAR into the extensions/druid-lookups-cached-global directory; wrong jdbcDriverClass; driver JAR present but not loaded via extension loading; using a driver incompatible with the JVM.

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 in the classpath
• 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/e8b0b0418fecf755. Report an issue: GitHub.