{"record":{"id":"6daa35c9b609c2aa","repo":"t8y2/dbx","slug":"custom-h2-driver-profile-requires-at-least-one-jdb","errorCode":null,"errorMessage":"Custom H2 driver profile requires at least one JDBC JAR path","messagePattern":"Custom H2 driver profile requires at least one JDBC JAR path","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java","lineNumber":44,"sourceCode":"        URLClassLoader classLoader = new URLClassLoader(\n            new URL[]{jar.toUri().toURL()},\n            H2DriverLoader.class.getClassLoader()\n        );\n        try {\n            Driver driver = (Driver) Class.forName(\"org.h2.Driver\", true, classLoader).getDeclaredConstructor().newInstance();\n            return new LoadedDriver(version, version.version(), driver, classLoader);\n        } catch (Exception error) {\n            closeAfterFailure(classLoader, error);\n            throw error;\n        } catch (LinkageError error) {\n            closeAfterFailure(classLoader, error);\n            throw error;\n        }\n    }\n\n    static LoadedDriver loadExternal(List<String> driverPaths, String driverClass) throws Exception {\n        if (driverPaths == null || driverPaths.isEmpty()) {\n            throw new IllegalArgumentException(\"Custom H2 driver profile requires at least one JDBC JAR path\");\n        }\n        List<URL> urls = new ArrayList<>();\n        List<String> identities = new ArrayList<>();\n        for (String driverPath : driverPaths) {\n            Path path = Path.of(driverPath).toAbsolutePath().normalize();\n            if (!Files.isRegularFile(path)) {\n                throw new IOException(\"Custom H2 JDBC JAR does not exist: \" + path);\n            }\n            urls.add(path.toUri().toURL());\n            identities.add(path + \":\" + sha256(path));\n        }\n        String effectiveDriverClass = driverClass == null || driverClass.isBlank() ? \"org.h2.Driver\" : driverClass.trim();\n        URLClassLoader classLoader = new URLClassLoader(\n            urls.toArray(new URL[0]),\n            H2DriverLoader.class.getClassLoader()\n        );\n        try {\n            Driver driver = (Driver) Class.forName(effectiveDriverClass, true, classLoader).getDeclaredConstructor().newInstance();","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java#L26-L62","documentation":"H2DriverLoader.loadExternal builds a URLClassLoader from user-supplied JAR paths for a custom H2 driver profile. If the driverPaths list is null or empty there is nothing to load, so it fails fast with IllegalArgumentException instead of silently falling back to a bundled driver.","triggerScenarios":"Calling loadExternal (directly or via the h2-custom profile loader) with driverPaths == null, an empty list, or a profile config that declared custom JARs but collected none.","commonSituations":"Config file with an h2-custom profile but the jdbc-jars/key listing was omitted; environment variable or CLI flag for the JAR path never set; path expansion in a shell yielded nothing (glob with no matches) so the list arrived empty.","solutions":["Provide at least one JDBC JAR path in the driverPaths list (e.g. /opt/drivers/h2-2.2.224.jar)","Verify the config key/environment variable that supplies the JAR paths is actually set and populated before constructing the profile","If the bundled driver is acceptable, switch the profile from h2-custom to h2/h2-auto instead"],"exampleFix":"// before\nH2DriverLoader.loadExternal(List.of(), \"org.h2.Driver\");\n// after\nH2DriverLoader.loadExternal(List.of(\"/opt/drivers/h2-2.2.224.jar\"), \"org.h2.Driver\");","handlingStrategy":"validation","validationCode":"if (driverPaths == null || driverPaths.isEmpty()) {\n    throw new IllegalStateException(\"h2-custom profile requires at least one JDBC JAR path\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    LoadedDriver d = H2DriverLoader.loadExternal(driverPaths, driverClass);\n} catch (IllegalArgumentException e) {\n    // fall back to bundled profile or surface config error\n}","preventionTips":["Validate the JAR list is non-empty at config-load time before constructing the profile","Fail fast at startup with a clear message listing the missing config key","Prefer the bundled h2-auto profile unless a custom JAR is truly required"],"tags":["h2","configuration","classpath","illegal-argument"],"backgroundTag":"missing-driver-jar","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"}