{"record":{"id":"5886a066ed2e5ef9","repo":"t8y2/dbx","slug":"h2-mvstore-file-is-too-small-to-contain-valid-head","errorCode":null,"errorMessage":"H2 MVStore file is too small to contain valid headers: \" + file","messagePattern":"H2 MVStore file is too small to contain valid headers: \" \\+ file","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2FileFormatDetector.java","lineNumber":46,"sourceCode":"        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        }\n        List<StoreHeader> headers = new ArrayList<>();\n        for (int block = 0; block < 2; block++) {\n            StoreHeader header = parseHeader(bytes, block * BLOCK_SIZE);\n            if (header != null) {\n                headers.add(header);\n            }\n        }\n        return headers.stream()\n            .max(Comparator.comparingLong(StoreHeader::version))\n            .orElseThrow(() -> new IOException(\"Cannot determine the H2 MVStore format for \" + file + \"; choose an explicit H2 driver profile\"))\n            .format();\n    }\n\n    private static StoreHeader parseHeader(byte[] fileBytes, int offset) {\n        byte[] block = java.util.Arrays.copyOfRange(fileBytes, offset, offset + BLOCK_SIZE);\n        int start = 0;\n        int end = block.length;","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2FileFormatDetector.java#L28-L64","documentation":"readMvStoreFormat reads the first two 4KB blocks of a .mv.db file because MVStore stores a header in each of the first two blocks. If fewer than BLOCK_SIZE*2 bytes can be read the file cannot hold valid headers, so an IOException is thrown instead of parsing garbage.","triggerScenarios":"detect() found a .mv.db file but readMvStoreFormat read < 8192 bytes — i.e. the file exists but is truncated, empty, or nearly empty.","commonSituations":"Zero-byte .mv.db created by a failed H2 startup; copy of the database interrupted mid-transfer; disk-full during a write truncated the file; empty placeholder file created by a script.","solutions":["Restore the .mv.db file from backup or re-copy it in full","Delete the truncated file if it is a leftover from a failed start and let H2 recreate the database","Check available disk space and re-run the copy with verification (checksum)"],"exampleFix":"// before\nls -la /data/app.mv.db  # 1024 bytes (truncated)\n// after\ncp /backups/app.mv.db /data/app.mv.db  # full copy, > 8KB","handlingStrategy":"validation","validationCode":"Path mv = Path.of(base + \".mv.db\");\nif (Files.isRegularFile(mv) && Files.size(mv) < 8192) {\n    throw new IllegalStateException(mv + \" is truncated/empty; restore from backup\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return H2Agent.connect(params);\n} catch (IOException e) {\n    if (e.getMessage().contains(\"too small to contain valid headers\")) {\n        // restore from backup or remove leftover file\n    }\n    throw e;\n}","preventionTips":["Check file sizes after copying/restoring H2 databases","Monitor disk space to avoid truncated writes","Treat zero-byte .mv.db files as failed-start artifacts to clean up"],"tags":["h2","corruption","filesystem","io"],"backgroundTag":"corrupt-database-file","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"}