apache/druid · critical · IllegalStateException

Could not find %s on the classpath. The MySQL Connector libr

Error message

Could not find %s on the classpath. The MySQL Connector library is not included in the Druid distribution but is required to use MySQL. Please download a compatible library (for example 'mysql-connector-j-8.2.0.jar') and place it under 'extensions/mysql-metadata-storage/'. See https://druid.apache.org/downloads for more details.

What it means

MySQLConnector tries to load the configured MySQL driver class via Class.forName; because Oracle licensing excludes the MySQL Connector/J from the Druid distribution, a missing class is a common, expected failure and Druid throws a detailed ISE telling you to download the driver JAR into extensions/mysql-metadata-storage/.

Source

Thrown at extensions-core/mysql-metadata-storage/src/main/java/org/apache/druid/metadata/storage/mysql/MySQLConnector.java:320

        // SQL standard unique constraint violation code is 23000 for MySQL
        if ("23000".equals(sqlState)) {
          return true;
        }
      }
      cause = cause.getCause();
    }
    return false;
  }

  @Nullable
  private Class<?> tryLoadDriverClass(String className, boolean failIfNotFound)
  {
    try {
      return Class.forName(className, false, getClass().getClassLoader());
    }
    catch (ClassNotFoundException e) {
      if (failIfNotFound) {
        throw new ISE(e, "Could not find %s on the classpath. The MySQL Connector library is not included in the Druid "
                         + "distribution but is required to use MySQL. Please download a compatible library (for example "
                         + "'mysql-connector-j-8.2.0.jar') and place it under 'extensions/mysql-metadata-storage/'. See "
                         + "https://druid.apache.org/downloads for more details.",
                      className
        );
      }
      log.warn("Could not find %s on the classpath.", className);
      return null;
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Download mysql-connector-j (or matching Connector/J) and place it under extensions/mysql-metadata-storage/
2. Verify druid.extensions.loadList contains mysql-metadata-storage and the extension directory is on the classpath
3. If a custom driverClass is set in the config, ensure the JAR actually provides that class

Example fix

// before
extensions/mysql-metadata-storage/   # only Druid jars
// after
wget https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.2.0/mysql-connector-j-8.2.0.jar \
  -P extensions/mysql-metadata-storage/

final File extDir = new File("extensions/mysql-metadata-storage");
if (!Arrays.stream(extDir.listFiles()).anyMatch(f -> f.getName().contains("mysql-connector"))) { throw new IllegalStateException("Copy mysql-connector-j JAR into extensions/mysql-metadata-storage/"); }

try { connector.init(); } catch (ISE e) { if (e.getMessage().contains("Could not find") && e.getMessage().contains("classpath")) { throw new DeploymentException("Install the MySQL Connector/J JAR per Druid docs"); } throw e; }

When it happens

Trigger: Enabling the mysql-metadata-storage extension without placing a compatible Connector/J JAR (e.g. mysql-connector-j-8.2.0.jar) in the extension directory, then starting Druid with MySQL metadata storage configured.

Common situations: Fresh Druid installs where users assume MySQL support is bundled; upgrading Druid and forgetting to re-copy the driver JAR into the new extensions directory; wrong JAR version incompatible with the configured driverClass.

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
• The Protobuf class [%s] is not known. Is your protobuf jar o
• Druid requires its MySQL database to be created with an UTF8

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