testcontainers/testcontainers-java · warning

Failed to register driver

Error message

Failed to register driver

What it means

ContainerDatabaseDriver's static initializer registers the driver with java.sql.DriverManager. If DriverManager.registerDriver throws a SQLException (most commonly because a conflicting driver is already registered or DriverManager refuses registration), the driver only logs this warning and continues instead of failing. Consequence: JDBC URLs with the jdbc:tc: scheme may later be rejected with 'No suitable driver' even though the class loaded.

Solutions

1. Check logs for the full SQLException stack trace attached to this warning
2. Remove duplicate testcontainers-jdbc / shaded driver copies so the class loads only once in one classloader
3. Register the driver explicitly once at startup (DriverManager.registerDriver(new ContainerDatabaseDriver())) inside try/catch and verify jdbc:tc: URLs connect

Example fix

// before: relying on static init that silently warned
Class.forName("org.testcontainers.jdbc.ContainerDatabaseDriver");
// after: explicit registration with verification
try {
    DriverManager.registerDriver(new ContainerDatabaseDriver());
} catch (SQLException e) {
    throw new IllegalStateException("jdbc:tc: driver registration failed", e);
}

try {
    Connection c = DriverManager.getConnection("jdbc:tc:postgresql:16:///db");
} catch (SQLException e) {
    if (e.getMessage().contains("No suitable driver")) {
        DriverManager.registerDriver(new ContainerDatabaseDriver());
    }
}

When it happens

Trigger: Static initialization of ContainerDatabaseDriver when DriverManager.registerDriver(new ContainerDatabaseDriver()) throws SQLException — e.g. the driver class is loaded twice in different classloaders, or a registerDriver failure occurs during JDBC 4 auto-loading from META-INF/services.

Common situations: Fat-shaded jars duplicating the driver class across classloaders in app servers; two versions of testcontainers-jdbc on the classpath; restrictive DriverManager setups.

Related errors

• The ClickHouse does not support this
• Database name not supported
• Could not load classpath init script
• Could not load classpath init script
• Error while executing init script

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

Appendix: source

Thrown at modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java:69

    private Driver delegate;

    private static final Map<String, Set<Connection>> containerConnections = new HashMap<>();

    private static final Map<String, JdbcDatabaseContainer> jdbcUrlContainerCache = new HashMap<>();

    private static final Set<String> initializedContainers = new HashSet<>();

    private static final String FILE_PATH_PREFIX = "file:";

    static {
        load();
    }

    private static void load() {
        try {
            DriverManager.registerDriver(new ContainerDatabaseDriver());
        } catch (SQLException e) {
            LOGGER.warn("Failed to register driver", e);
        }
    }

    @Override
    public boolean acceptsURL(String url) throws SQLException {
        return url.startsWith("jdbc:tc:");
    }

    @Override
    public synchronized Connection connect(String url, final Properties info) throws SQLException {
        /*
          The driver should return "null" if it realizes it is the wrong kind of driver to connect to the given URL.
         */
        if (!acceptsURL(url)) {
            return null;
        }

        ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);

View on GitHub (pinned to 8e549514e3)