{"record":{"id":"7582ac5d40899735","repo":"t8y2/dbx","slug":"both-h2-pagestore-and-mvstore-files-exist-for","errorCode":null,"errorMessage":"Both H2 PageStore and MVStore files exist for \" + base + \"; choose an explicit H2 driver profile","messagePattern":"Both H2 PageStore and MVStore files exist for \" \\+ base \\+ \"; choose an explicit H2 driver profile","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2FileFormatDetector.java","lineNumber":29,"sourceCode":"import java.util.OptionalInt;\n\nfinal class H2FileFormatDetector {\n    private static final int BLOCK_SIZE = 4096;\n\n    private H2FileFormatDetector() {\n    }\n\n    static OptionalInt detect(String jdbcUrl) throws IOException {\n        Path base = localDatabaseBasePath(jdbcUrl);\n        if (base == null) {\n            return OptionalInt.empty();\n        }\n        Path pageStore = withSuffix(base, \".h2.db\");\n        Path mvStore = withSuffix(base, \".mv.db\");\n        boolean pageStoreExists = Files.isRegularFile(pageStore);\n        boolean mvStoreExists = Files.isRegularFile(mvStore);\n        if (pageStoreExists && mvStoreExists) {\n            throw new IOException(\"Both H2 PageStore and MVStore files exist for \" + base + \"; choose an explicit H2 driver profile\");\n        }\n        if (pageStoreExists) {\n            return OptionalInt.of(1);\n        }\n        if (!mvStoreExists) {\n            return OptionalInt.empty();\n        }\n        return OptionalInt.of(readMvStoreFormat(mvStore));\n    }\n\n    private static int readMvStoreFormat(Path file) throws IOException {\n        byte[] bytes;\n        try (InputStream input = Files.newInputStream(file)) {\n            bytes = input.readNBytes(BLOCK_SIZE * 2);\n        }\n        if (bytes.length < BLOCK_SIZE * 2) {\n            throw new IOException(\"H2 MVStore file is too small to contain valid headers: \" + file);\n        }","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2FileFormatDetector.java#L11-L47","documentation":"H2FileFormatDetector distinguishes PageStore (base.h2.db) from MVStore (base.mv.db) databases by checking which files exist. When BOTH exist it cannot decide which engine owns the data and refuses to guess, raising an IOException that asks for an explicit driver profile.","triggerScenarios":"detect(base) finds both '<base>.h2.db' and '<base>.mv.db' as regular files in the database directory.","commonSituations":"Database was migrated from old H2 (1.4-) to MVStore and leftover .h2.db files were never removed; backup files placed next to live DB; a copy of another database dropped into the same directory.","solutions":["Rename/move the stale .h2.db (PageStore) file out of the directory if the live database is MVStore","Explicitly set the driver profile (h2-v1 for PageStore or h2-v3 for MVStore) to bypass auto-detection","Determine which file is current (check mtimes/open transaction logs) before deleting anything"],"exampleFix":"// before\ndetect(Path.of(\"/data/app\")); // both /data/app.h2.db and /data/app.mv.db exist\n// after\nmv /data/app.h2.db /data/app.h2.db.old  # then auto-detect succeeds\n// or: profile = \"h2-v3\"","handlingStrategy":"validation","validationCode":"boolean page = Files.isRegularFile(Path.of(base + \".h2.db\"));\nboolean mv = Files.isRegularFile(Path.of(base + \".mv.db\"));\nif (page && mv) throw new IllegalStateException(\"both PageStore and MVStore files present for \" + base);","typeGuard":null,"tryCatchPattern":"try {\n    return H2Agent.connect(params);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"Both H2 PageStore and MVStore\")) {\n        params.put(\"driverProfile\", \"h2-v3\"); // or clean up stale file\n    }\n    throw e;\n}","preventionTips":["After migrating from H2 1.4- (PageStore) to MVStore, archive or delete old .h2.db files","Keep backups out of the live database directory","Set an explicit driver profile for databases where both artifacts may appear"],"tags":["h2","filesystem","ambiguity","format-detection"],"backgroundTag":"ambiguous-database-format","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"}