{"record":{"id":"cdb972ba7766c68c","repo":"testcontainers/testcontainers-java","slug":"failed-to-register-driver","errorCode":null,"errorMessage":"Failed to register driver","messagePattern":"Failed to register driver","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java","lineNumber":69,"sourceCode":"    private Driver delegate;\n\n    private static final Map<String, Set<Connection>> containerConnections = new HashMap<>();\n\n    private static final Map<String, JdbcDatabaseContainer> jdbcUrlContainerCache = new HashMap<>();\n\n    private static final Set<String> initializedContainers = new HashSet<>();\n\n    private static final String FILE_PATH_PREFIX = \"file:\";\n\n    static {\n        load();\n    }\n\n    private static void load() {\n        try {\n            DriverManager.registerDriver(new ContainerDatabaseDriver());\n        } catch (SQLException e) {\n            LOGGER.warn(\"Failed to register driver\", e);\n        }\n    }\n\n    @Override\n    public boolean acceptsURL(String url) throws SQLException {\n        return url.startsWith(\"jdbc:tc:\");\n    }\n\n    @Override\n    public synchronized Connection connect(String url, final Properties info) throws SQLException {\n        /*\n          The driver should return \"null\" if it realizes it is the wrong kind of driver to connect to the given URL.\n         */\n        if (!acceptsURL(url)) {\n            return null;\n        }\n\n        ConnectionUrl connectionUrl = ConnectionUrl.newInstance(url);","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"Fat-shaded jars duplicating the driver class across classloaders in app servers; two versions of testcontainers-jdbc on the classpath; restrictive DriverManager setups.","solutions":["Check logs for the full SQLException stack trace attached to this warning","Remove duplicate testcontainers-jdbc / shaded driver copies so the class loads only once in one classloader","Register the driver explicitly once at startup (DriverManager.registerDriver(new ContainerDatabaseDriver())) inside try/catch and verify jdbc:tc: URLs connect"],"exampleFix":"// before: relying on static init that silently warned\nClass.forName(\"org.testcontainers.jdbc.ContainerDatabaseDriver\");\n// after: explicit registration with verification\ntry {\n    DriverManager.registerDriver(new ContainerDatabaseDriver());\n} catch (SQLException e) {\n    throw new IllegalStateException(\"jdbc:tc: driver registration failed\", e);\n}","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    Connection c = DriverManager.getConnection(\"jdbc:tc:postgresql:16:///db\");\n} catch (SQLException e) {\n    if (e.getMessage().contains(\"No suitable driver\")) {\n        DriverManager.registerDriver(new ContainerDatabaseDriver());\n    }\n}","preventionTips":["Avoid shaded/duplicated testcontainers-jdbc jars on the classpath","Load the driver class once, explicitly, at startup and assert registration succeeded","Grep startup logs for 'Failed to register driver' in CI"],"tags":["jdbc","driver-registration","classloader","testcontainers"],"backgroundTag":"module-init-failed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}