apache/druid · error · RuntimeException

Failed to find MySQL driver class. Please check the MySQL co

Error message

Failed to find MySQL driver class. Please check the MySQL connector version 8.2.0 is in the classpath

What it means

tryParseJdbcUriParameters attempts to parse a jdbc:mysql:... URI using the MySQL Connector/J 8.x driver class reflectively (Class.forName), falling back to MariaDB drivers. If the MySQL driver class is absent AND both MariaDB driver versions are also absent/unresolvable, it rethrows this RuntimeException naming MySQL connector 8.2.0 as the required dependency.

Source

Thrown at processing/src/main/java/org/apache/druid/utils/ConnectionUriUtils.java:115

   * If the uri does not match any of these schemes, this method will return an empty set if unknown uris are allowed,
   * or throw an exception if not.
   */
  public static Set<String> tryParseJdbcUriParameters(String connectionUri, boolean allowUnknown)
  {
    if (connectionUri.startsWith(MYSQL_PREFIX)) {
      try {
        return tryParseMySqlConnectionUri(connectionUri);
      }
      catch (ClassNotFoundException notFoundMysql) {
        try {
          return tryParseMariaDb2xConnectionUri(connectionUri);
        }
        catch (ClassNotFoundException notFoundMaria2x) {
          try {
            return tryParseMariaDb3xConnectionUri(connectionUri);
          }
          catch (ClassNotFoundException notFoundMaria3x) {
            throw new RuntimeException(
                "Failed to find MySQL driver class. Please check the MySQL connector version 8.2.0 is in the classpath",
                notFoundMysql
            );
          }
          catch (IllegalArgumentException iaeMaria3x) {
            throw iaeMaria3x;
          }
          catch (Throwable otherMaria3x) {
            throw new RuntimeException(otherMaria3x);
          }
        }
        catch (IllegalArgumentException iaeMaria2x) {
          throw iaeMaria2x;
        }
        catch (Throwable otherMaria2x) {
          throw new RuntimeException(otherMaria2x);
        }
      }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add mysql-connector-j (8.2.0 or compatible) to the classpath / extensions directory.
2. Alternatively install a MariaDB connector (2.x or 3.x) which the fallback path can use for mysql URIs.
3. Verify the driver class is loadable: Class.forName("com.mysql.cj.jdbc.Driver") and check the extension is listed in druid.extensions.loadList.
4. Align connector versions with the Druid version's documented metadata-storage dependencies.

Example fix

// before: running without any MySQL/MariaDB driver jar
// after: add to extensions dir or pom
// <dependency>
//   <groupId>com.mysql</groupId>
//   <artifactId>mysql-connector-j</artifactId>
//   <version>8.2.0</version>
// </dependency>

static boolean mysqlDriverPresent() {
  try {
    Class.forName("com.mysql.cj.jdbc.Driver");
    return true;
  } catch (ClassNotFoundException e) {
    return false;
  }
}

try {
  params = ConnectionUriUtils.tryParseJdbcUriParameters(uri, false);
} catch (RuntimeException e) {
  if (e.getMessage().startsWith("Failed to find MySQL driver class")) {
    log.error("MySQL connector missing from classpath; add mysql-connector-j");
  }
  throw e;
}

When it happens

Trigger: Calling ConnectionUriUtils.tryParseJdbcUriParameters on a jdbc:mysql URI in a runtime that has none of mysql-connector-j 8.x, mariadb 2.x, or mariadb 3.x classes on the classpath.

Common situations: Extensions-metadata deployments missing the mysql-metadata-storage extension, slimmed containers where JDBC jars were excluded, or a version bump where the expected driver class names moved between connector versions.

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

• Failed to find MariaDB driver class. Please check the MariaD
• JDBC driver JAR files missing from extensions/druid-lookups-
• JDBC driver JAR files missing in the classpath
• Could not find %s on the classpath. The MySQL Connector libr
• Invalid URL format for MySQL: [%s]

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