{"record":{"id":"645c5b9ea77ab269","repo":"t8y2/dbx","slug":"custom-h2-jdbc-jar-does-not-exist-path","errorCode":null,"errorMessage":"Custom H2 JDBC JAR does not exist: \" + path","messagePattern":"Custom H2 JDBC JAR does not exist: \" \\+ path","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java","lineNumber":51,"sourceCode":"        } 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();\n            return new LoadedDriver(H2DriverVersion.CUSTOM, effectiveDriverClass + \"|\" + String.join(\"|\", identities), driver, classLoader);\n        } catch (Exception error) {\n            closeAfterFailure(classLoader, error);\n            throw error;\n        } catch (LinkageError error) {\n            closeAfterFailure(classLoader, error);\n            throw error;","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java#L33-L69","documentation":"loadExternal validates each configured JAR path: it resolves to an absolute normalized Path and requires it to be a regular file. A configured path that does not exist (or is a directory) causes this IOException so the loader never builds a class loader over bogus URLs.","triggerScenarios":"Calling loadExternal with a driverPaths entry pointing to a nonexistent file, a deleted/moved JAR, or a directory path.","commonSituations":"JAR deleted by cleanup job or upgrade script; relative path resolved from a different working directory; typo in the configured path; JAR is on a not-yet-mounted volume.","solutions":["Correct the configured path to point at an existing JDBC JAR file (verify with ls / Files.exists)","Copy the H2 JAR to the expected location before starting the agent","Use an absolute path in configuration so it does not depend on the process working directory"],"exampleFix":"// before\nH2DriverLoader.loadExternal(List.of(\"/opt/drivers/h2.jar\"), null); // file deleted\n// after\nH2DriverLoader.loadExternal(List.of(\"/opt/drivers/h2-2.2.224.jar\"), null); // file present","handlingStrategy":"validation","validationCode":"List<String> valid = driverPaths.stream()\n    .filter(p -> Files.isRegularFile(Path.of(p).toAbsolutePath().normalize()))\n    .toList();\nif (valid.size() != driverPaths.size()) throw new IllegalStateException(\"missing JAR(s)\");","typeGuard":null,"tryCatchPattern":"try {\n    return H2DriverLoader.loadExternal(driverPaths, driverClass);\n} catch (IOException e) {\n    logger.error(\"Configured H2 JAR missing: {}\", e.getMessage());\n    throw new ConfigurationException(e);\n}","preventionTips":["Use absolute paths for driver JARs in configuration","Check Files.exists for each path during application startup health checks","Pin JARs to a dedicated drivers directory excluded from cleanup jobs"],"tags":["h2","filesystem","classpath","io"],"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"}