t8y2/dbx · error · IllegalArgumentException

Unsupported H2 database file format: " + format

Error message

Unsupported H2 database file format: " + format

What it means

H2FileFormatDetector detects the storage format from on-disk files and H2DriverVersion.fromStorageFormat maps the detected numeric format (1=PageStore, 2/3=MVStore versions) to a driver version. Formats outside 1..3 indicate corrupt or unrecognized header data, so this IllegalArgumentException is thrown.

Source

Thrown at agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2DriverVersion.java:62

        return switch (normalized) {
            case "h2-v1" -> V1;
            case "h2-v2", "h2-legacy" -> V2;
            case "h2-v3" -> V3;
            case "h2-custom" -> CUSTOM;
            case "", "h2", "h2-auto", "h2_embedded", "h2_server" -> {
                java.util.OptionalInt detected = H2FileFormatDetector.detect(H2Agent.buildUrl(params));
                yield detected.isPresent() ? fromStorageFormat(detected.getAsInt()) : V3;
            }
            default -> throw new IllegalArgumentException("Unsupported H2 driver profile: " + profile);
        };
    }

    private static H2DriverVersion fromStorageFormat(int format) {
        return switch (format) {
            case 1 -> V1;
            case 2 -> V2;
            case 3 -> V3;
            default -> throw new IllegalArgumentException("Unsupported H2 database file format: " + format);
        };
    }
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Verify the database file with the H2 Shell tool (java -cp h2.jar org.h2.tools.Shell) to check integrity and actual version
2. Restore the database from backup if headers are corrupted
3. Upgrade the driver module to a version that supports the newer storage format

Example fix

// before (corrupt header detected as format 7)
// fromStorageFormat(7) -> throws
// after: restore valid DB file
// detect(base) -> 3 -> V3

try {
    H2DriverVersion v = H2DriverVersion.select(profile, params);
} catch (IllegalArgumentException e) {
    // detected format unsupported: check DB integrity / upgrade driver
    throw new RuntimeException("H2 file format not supported by this agent; restore or upgrade", e);
}

When it happens

Trigger: H2FileFormatDetector.detect returned an unexpected integer (e.g. from a corrupted or future-format MVStore header) which is then passed to fromStorageFormat.

Common situations: Database file corrupted by a crash or partial write; H2 database created by a newer H2 version with an unknown format code; a non-H2 file renamed to .mv.db and scanned.

Related errors

• Custom H2 driver profile requires at least one JDBC JAR path
• Unsupported H2 driver profile: " + profile
• Both H2 PageStore and MVStore files exist for " + base + ";
• H2 MVStore file is too small to contain valid headers: " + f
• Query session not found: {sessionId}

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/4cbbbef7da9511f0. Report an issue: GitHub.