apache/druid · error · RuntimeException

Failed to find MariaDB driver class. Please check the MariaD

Error message

Failed to find MariaDB driver class. Please check the MariaDB connector is in the classpath

What it means

tryParseJdbcUriParameters, when handling a mysql JDBC URI, first tries MySQL Connector/J, then MariaDB 3.x, then MariaDB 2.x. If all three driver classes are missing from the classpath, it throws this RuntimeException telling the user to add a MariaDB connector (chained from the first ClassNotFoundException).

Source

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

          throw new RuntimeException(otherMaria2x);
        }
      }
      catch (IllegalArgumentException iaeMySql) {
        throw iaeMySql;
      }
      catch (Throwable otherMysql) {
        throw new RuntimeException(otherMysql);
      }
    } else if (connectionUri.startsWith(MARIADB_PREFIX)) {
      try {
        return tryParseMariaDb2xConnectionUri(connectionUri);
      }
      catch (ClassNotFoundException notFoundMaria2x) {
        try {
          return tryParseMariaDb3xConnectionUri(connectionUri);
        }
        catch (ClassNotFoundException notFoundMaria3x) {
          throw new RuntimeException(
              "Failed to find MariaDB driver class. Please check the MariaDB connector is in the classpath",
              notFoundMaria2x
          );
        }
        catch (IllegalArgumentException iaeMaria3x) {
          throw iaeMaria3x;
        }
        catch (Throwable otherMaria3x) {
          throw new RuntimeException(otherMaria3x);
        }
      }
      catch (IllegalArgumentException iaeMaria2x) {
        throw iaeMaria2x;
      }
      catch (Throwable otherMaria2x) {
        throw new RuntimeException(otherMaria2x);
      }
    } else if (connectionUri.startsWith(POSTGRES_PREFIX)) {

View on GitHub (pinned to 9b90983fd2)

Solutions

Add the MariaDB connector jar (org.mariadb.jdbc) to the classpath/extensions directory.
Or add mysql-connector-j so the primary MySQL path succeeds first.
Check druid.extensions.loadList includes mysql-metadata-storage or equivalent.
Verify the expected driver class names match your connector version (package names changed across MariaDB 2.x/3.x).

Example fix

// before: no MariaDB driver installed, mysql URI being parsed
// after: add to classpath
// <dependency>
//   <groupId>org.mariadb.jdbc</groupId>
//   <artifactId>mariadb-java-client</artifactId>
//   <version>3.3.3</version>
// </dependency>

Defensive patterns

Strategy: try-catch

Validate before calling

static boolean mariaDbDriverPresent() {
  try {
    Class.forName("org.mariadb.jdbc.Driver");
    return true;
  } catch (ClassNotFoundException e) {
    return false;
  }
}

Try / catch

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

Prevention

Ship a MariaDB connector jar (or MySQL connector) with the deployment
Check driver class names after upgrading MariaDB connector majors (2.x vs 3.x packages differ)
Validate extension loadList at startup
Run a JDBC connectivity smoke test before processing mysql URIs

When it happens

Trigger: Parsing a jdbc:mysql URI when the MySQL 8.x driver is absent and both MariaDB driver major versions are also not on the classpath.

Common situations: Minimal Druid distributions without any MySQL/MariaDB metadata-storage extension, custom builds that pruned JDBC jars, or MariaDB connector upgrades that changed the driver class package names out from under the reflective lookup.

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

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