t8y2/dbx · error · SQLException

H2 JDBC driver rejected URL: " + buildJdbcUrl(params)

Error message

H2 JDBC driver rejected URL: " + buildJdbcUrl(params)

What it means

H2's java.sql.Driver.connect returns null when it does not recognize the JDBC URL. H2Agent detects this and throws SQLException('H2 JDBC driver rejected URL: ...') including the constructed URL, signaling the URL is malformed or uses an unknown scheme/protocol.

Source

Thrown at agents/drivers/h2/src/main/java/com/dbx/agent/h2/H2Agent.java:87

        if (previous != null) {
            try {
                previous.classLoader().close();
            } catch (Exception error) {
                replacement.classLoader().close();
                throw error;
            }
        }
        loadedDriver = replacement;
    }

    @Override
    protected Connection openConnection(ConnectParams params) throws Exception {
        if (loadedDriver == null) {
            throw new IllegalStateException("H2 JDBC driver was not loaded");
        }
        Connection opened = loadedDriver.driver().connect(buildJdbcUrl(params), buildConnectionProperties(params));
        if (opened == null) {
            throw new SQLException("H2 JDBC driver rejected URL: " + buildJdbcUrl(params));
        }
        return opened;
    }

    @Override
    protected void afterConnect(ConnectParams params, Connection connection) {
        databaseName = params.getDatabase();
        databaseMajorVersion = unchecked(() -> connection.getMetaData().getDatabaseMajorVersion());
    }

    H2DriverVersion driverVersion() {
        return driverVersion;
    }

    boolean isVersion2OrLater() {
        return databaseMajorVersion >= 2;
    }

View on GitHub (pinned to c0390bff16)

Solutions

Check the generated JDBC URL starts with jdbc:h2: and uses a valid form (jdbc:h2:mem:, file:, tcp:, etc.)
Print/log buildJdbcUrl(params) output and compare against H2 URL syntax docs
Fix ConnectParams (host, path, mode, in-memory vs server) feeding the URL builder

Example fix

// before
String url = "h2:mem:testdb;DB_CLOSE_DELAY=-1"; // rejected: missing jdbc: prefix
Driver d = DriverManager.getDriver(url); // returns null
// after
String url = "jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1";
Driver d = DriverManager.getDriver(url); // recognized

Defensive patterns

Strategy: validation

Validate before calling

String url = buildJdbcUrl(params); if (!url.startsWith("jdbc:h2:")) { throw new IllegalArgumentException("Not a valid H2 JDBC URL: " + url); }

Type guard

static boolean isH2Url(String url) { return url != null && url.startsWith("jdbc:h2:(mem|file|tcp|ssl|nio|mvstore)"); }

Try / catch

try { conn = agent.connect(params); } catch (SQLException e) { if (e.getMessage() != null && e.getMessage().contains("rejected URL")) { log.error("Malformed H2 URL: {}", e.getMessage()); } throw e; }

Prevention

Always start H2 URLs with jdbc:h2: (a missing prefix is the #1 cause)
Validate URL templates so placeholders cannot reach the driver unresolved
Match URL mode (mem/file/tcp) to your deployment; run an H2 TCP server for jdbc:h2:tcp
Log the exact generated URL when connection setup fails

When it happens

Trigger: buildJdbcUrl(params) produces a URL the H2 driver does not accept, e.g. wrong prefix, unsupported mode, or garbage from misconfigured connection properties.

Common situations: Typo like 'h2:mem:db' (missing jdbc:); using h2:tcp against a server that is not running with unsupported settings; property placeholder left unresolved in the URL template.

Related errors

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