{"record":{"id":"4ee69988c02fb3e6","repo":"t8y2/dbx","slug":"bundled-h2-driver-is-missing-version-resource","errorCode":null,"errorMessage":"Bundled H2 driver is missing: \" + version.resourcePath()","messagePattern":"Bundled H2 driver is missing: \" \\+ version\\.resourcePath\\(\\)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java","lineNumber":77,"sourceCode":"            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;\n        }\n    }\n\n    private static Path extract(H2DriverVersion version) throws Exception {\n        byte[] bytes;\n        try (InputStream input = H2DriverLoader.class.getResourceAsStream(version.resourcePath())) {\n            if (input == null) {\n                throw new IOException(\"Bundled H2 driver is missing: \" + version.resourcePath());\n            }\n            bytes = input.readAllBytes();\n        }\n        String digest = sha256(bytes);\n        Path directory = CACHE_ROOT.resolve(version.version() + \"-\" + digest.substring(0, 16));\n        Path target = directory.resolve(\"h2.jar\");\n        synchronized (EXTRACTION_LOCK) {\n            Files.createDirectories(directory);\n            if (!Files.isRegularFile(target) || Files.size(target) != bytes.length || !digest.equals(sha256(target))) {\n                Path temporary = directory.resolve(\"h2.jar.tmp-\" + UUID.randomUUID());\n                Files.write(temporary, bytes);\n                try {\n                    Files.move(temporary, target, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);\n                } catch (java.nio.file.AtomicMoveNotSupportedException ignored) {\n                    Files.move(temporary, target, StandardCopyOption.REPLACE_EXISTING);\n                }\n            }\n        }","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverLoader.java#L59-L95","documentation":"extract() materializes a bundled H2 JAR from the classpath resource given by H2DriverVersion.resourcePath() into a cache directory. If getResourceAsStream returns null the bundled artifact was not packaged into the application, so an IOException is thrown rather than proceeding with a null stream.","triggerScenarios":"Calling H2DriverLoader.jar() for a version (V1/V2/V3) whose embedded driver resource is absent from the classpath — e.g. the resource was excluded from the build or the loader JAR was repackaged without it.","commonSituations":"Fat-jar/shade build dropped resources under com/dbx/agent/h2/; resource filtered out by Maven/Gradle excludes; running from an IDE with incomplete classpath; custom build stripped embedded binaries.","solutions":["Rebuild/repackage the driver module so the embedded H2 JAR resource is included (check shading excludes/resource filtering)","Verify the resource exists on the classpath at version.resourcePath() (e.g. via Class.getResource)","Configure a custom driver profile (h2-custom) with an external JAR path to bypass the bundled resource"],"exampleFix":"// before (maven-shade)\n<exclude>com/dbx/agent/h2/drivers/*</exclude>\n// after\n<!-- remove the exclude so bundled h2 jars ship in the artifact -->","handlingStrategy":"try-catch","validationCode":"boolean bundled = H2DriverLoader.class.getResource(version.resourcePath()) != null;","typeGuard":null,"tryCatchPattern":"try {\n    Path jar = H2DriverLoader.jar(version);\n} catch (IOException e) {\n    // fall back to h2-custom external JAR path\n    return H2DriverLoader.loadExternal(externalJars, driverClass);\n}","preventionTips":["Verify shading/resource-filtering config keeps com/dbx/agent/h2 resources in the artifact","Add a smoke test that loads the bundled resource in CI","Run the app from a complete distribution, not a partially assembled classpath"],"tags":["h2","classpath","packaging","resources"],"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-14T00:17:10.932Z"}