t8y2/dbx · error · IllegalArgumentException

Unsupported H2 driver profile: " + profile

Error message

Unsupported H2 driver profile: " + profile

What it means

H2DriverVersion.select maps a named driver profile string to a driver version. Only a fixed set of names is recognized (h2-v1/h2-v2/h2-v3, h2-custom, and auto aliases). Any other string is rejected with IllegalArgumentException so typos never fall through to a wrong driver.

Source

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

    }

    int storageFormat() {
        return storageFormat;
    }

    static H2DriverVersion select(ConnectParams params) throws Exception {
        String profile = params.getDriver_profile();
        String normalized = profile == null ? "" : profile.trim().toLowerCase(Locale.ROOT);
        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. Use one of the supported profile names: h2-v1, h2-v2, h2-v3, h2-custom, or the auto aliases ("", h2, h2-auto, h2_embedded, h2_server)
2. Check spelling and casing of the configured profile value
3. If auto-detection is acceptable, set the profile to h2-auto and let the file-format detector choose

Example fix

// before
params.put("driverProfile", "h2-2.x");
// after
params.put("driverProfile", "h2-v3");

Set<String> allowed = Set.of("", "h2", "h2-auto", "h2_embedded", "h2_server", "h2-v1", "h2-v2", "h2-v3", "h2-custom");
if (!allowed.contains(profile)) throw new IllegalArgumentException("bad profile: " + profile);

try {
    H2DriverVersion v = H2DriverVersion.select(profile, params);
} catch (IllegalArgumentException e) {
    // report invalid config value with the allowed names
}

When it happens

Trigger: Passing an unrecognized profile string (e.g. 'H2-V2', 'h2 2.x', 'h2-legacy') to select() via connection params/config.

Common situations: Typo or wrong casing in the profile config value; copied config from an older release whose profile names changed; invented profile name expecting a custom mapping.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Agent runtime thread limits must be positive
• Custom H2 driver profile requires at least one JDBC JAR path
• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)
• Unsupported H2 database file format: " + format
• JDBC URL is required.

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