testcontainers/testcontainers-java · critical · java.lang.RuntimeException

Can't find valid driver class for OceanBase

Error message

Can't find valid driver class for OceanBase

What it means

OceanBaseJdbcUtils.getDriverClass() iterates candidate OceanBase JDBC driver class names and calls Class.forName on each. If none of the candidate driver classes (MySQL-compatible or OceanBase-specific drivers) are present on the classpath, it throws a RuntimeException. The container needs a JDBC driver on the test classpath to build JDBC URLs and wait strategies.

Solutions

1. Add com.oceanbase:oceanbase-client to the test classpath.
2. Alternatively add com.mysql:mysql-connector-j (or legacy mysql:mysql-connector-java), which OceanBase MySQL mode accepts.
3. Verify the driver jar version exposes the expected class name that OceanBaseJdbcUtils probes.

Example fix

// before
testImplementation 'org.testcontainers:oceanbase'
// after
testImplementation 'org.testcontainers:oceanbase'
testImplementation 'com.oceanbase:oceanbase-client:2.4.9'

try {
    Class.forName("com.alipay.oceanbase.jdbc.Driver");
} catch (ClassNotFoundException e) {
    try {
        Class.forName("com.mysql.cj.jdbc.Driver");
    } catch (ClassNotFoundException e2) {
        throw new IllegalStateException("Add oceanbase-client or mysql-connector-j to the test classpath");
    }
}

try {
    String driverClass = OceanBaseJdbcUtils.getDriverClass();
} catch (RuntimeException e) {
    throw new IllegalStateException("OceanBase JDBC driver missing from classpath", e);
}

When it happens

Trigger: Creating an OceanBaseContainer / using OceanBaseJdbcUtils without any of the supported drivers (oceanbase-client, mysql-connector-java/mysql-connector-j) on the classpath.

Common situations: Forgetting to add the OceanBase or MySQL JDBC dependency to test scope; using a custom driver version whose class name isn't in the candidate list.

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

• Could not get Driver
• Database name not supported
• Could not load classpath init script
• Can't transfer
• Configured Image Substitutor could not be loaded

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/562aedca536a946d. Report an issue: GitHub.

Appendix: source

Thrown at modules/oceanbase/src/main/java/org/testcontainers/oceanbase/OceanBaseJdbcUtils.java:35

    static final String OCEANBASE_LEGACY_JDBC_DRIVER = "com.alipay.oceanbase.jdbc.Driver";

    static final List<String> SUPPORTED_DRIVERS = Arrays.asList(
        OCEANBASE_JDBC_DRIVER,
        OCEANBASE_LEGACY_JDBC_DRIVER,
        MYSQL_JDBC_DRIVER,
        MYSQL_LEGACY_JDBC_DRIVER
    );

    static String getDriverClass() {
        for (String driverClass : SUPPORTED_DRIVERS) {
            try {
                Class.forName(driverClass);
                return driverClass;
            } catch (ClassNotFoundException e) {
                // try to load next driver
            }
        }
        throw new RuntimeException("Can't find valid driver class for OceanBase");
    }

    static boolean isMySQLDriver(String driverClassName) {
        return MYSQL_JDBC_DRIVER.equals(driverClassName) || MYSQL_LEGACY_JDBC_DRIVER.equals(driverClassName);
    }

    static boolean isOceanBaseDriver(String driverClassName) {
        return OCEANBASE_JDBC_DRIVER.equals(driverClassName) || OCEANBASE_LEGACY_JDBC_DRIVER.equals(driverClassName);
    }
}

View on GitHub (pinned to 8e549514e3)