{"record":{"id":"2a7dc272d4a8c0c3","repo":"t8y2/dbx","slug":"h2-jdbc-driver-was-not-loaded","errorCode":null,"errorMessage":"H2 JDBC driver was not loaded","messagePattern":"H2 JDBC driver was not loaded","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2Agent.java","lineNumber":83,"sourceCode":"    }\n\n    private void replaceLoadedDriver(H2DriverLoader.LoadedDriver replacement) throws Exception {\n        H2DriverLoader.LoadedDriver previous = loadedDriver;\n        if (previous != null) {\n            try {\n                previous.classLoader().close();\n            } catch (Exception error) {\n                replacement.classLoader().close();\n                throw error;\n            }\n        }\n        loadedDriver = replacement;\n    }\n\n    @Override\n    protected Connection openConnection(ConnectParams params) throws Exception {\n        if (loadedDriver == null) {\n            throw new IllegalStateException(\"H2 JDBC driver was not loaded\");\n        }\n        Connection opened = loadedDriver.driver().connect(buildJdbcUrl(params), buildConnectionProperties(params));\n        if (opened == null) {\n            throw new SQLException(\"H2 JDBC driver rejected URL: \" + buildJdbcUrl(params));\n        }\n        return opened;\n    }\n\n    @Override\n    protected void afterConnect(ConnectParams params, Connection connection) {\n        databaseName = params.getDatabase();\n        databaseMajorVersion = unchecked(() -> connection.getMetaData().getDatabaseMajorVersion());\n    }\n\n    H2DriverVersion driverVersion() {\n        return driverVersion;\n    }\n","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2Agent.java#L65-L101","documentation":"H2Agent keeps a loaded JDBC driver reference injected at startup. openConnection throws IllegalStateException when that reference is null, meaning no H2 driver was registered/loaded before connecting, so no connection can be established.","triggerScenarios":"openConnection is invoked before the driver was loaded/set (loadedDriver == null), e.g. missing H2 jar on the classpath or driver initialization step skipped.","commonSituations":"H2 dependency excluded from the build; custom classloader (plugin/app-server) not seeing the driver jar; initialization order calling connect before driver setup; shaded jar missing driver classes.","solutions":["Add the H2 JDBC driver dependency (com.h2database:h2) to the classpath","Ensure the driver loading/initialization hook runs before openConnection","Verify no shading/classloader isolation hides the driver class"],"exampleFix":"// before\nConnection c = agent.connect(params); // driver never loaded\n// after\nClass.forName(\"org.h2.Driver\"); // or call agent's driver-load/init hook\nConnection c = agent.connect(params);","handlingStrategy":"validation","validationCode":"try { Class.forName(\"org.h2.Driver\"); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"H2 driver missing from classpath; add com.h2database:h2\", e); }","typeGuard":"static boolean h2DriverAvailable() { try { Class.forName(\"org.h2.Driver\"); return true; } catch (ClassNotFoundException e) { return false; } }","tryCatchPattern":"try { conn = agent.connect(params); } catch (IllegalStateException e) { if (e.getMessage().contains(\"driver was not loaded\")) { initDriver(); conn = agent.connect(params); } else throw e; }","preventionTips":["Add com.h2database:h2 as a runtime dependency","Ensure driver initialization runs before any connect call","Check shaded/fat jars actually include org.h2.Driver","Verify custom classloaders can see the driver class"],"tags":["h2","jdbc","missing-driver","state","initialization"],"backgroundTag":"jdbc-driver-not-loaded","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}