t8y2/dbx · error · IllegalArgumentException

JDBC URL is required.

Error message

JDBC URL is required.

What it means

openConnection builds the effective JDBC URL from the connection JSON; when jdbcUrl() returns null (no url/jdbcUrl field and no derivable components), it throws this IllegalArgumentException before attempting any connection. The plugin requires an explicit or derivable JDBC URL to know which driver and database to target.

Source

Thrown at plugins/jdbc/src/main/java/app/dbx/jdbc/DbxJdbcPlugin.java:629

        for (Driver driver : ServiceLoader.load(Driver.class, loader)) {
            Driver shim = new DriverShim(driver);
            if (first == null) {
                first = shim;
            }
            DriverManager.registerDriver(shim);
            loaded = true;
        }
        if (!loaded && !urls.isEmpty()) {
            throw new IllegalArgumentException("No JDBC driver was discovered. Enter the driver class name for this JAR.");
        }
        registeredDriver = first;
        registeredDriverKey = driverKey;
    }

    private static Connection openConnection(JsonNode connection) throws SQLException {
        String url = jdbcUrl(connection);
        if (url == null) {
            throw new IllegalArgumentException("JDBC URL is required.");
        }
        String key = connectionKey(connection);
        if (sharedConnection != null && key.equals(sharedConnectionKey) && !isConnectionClosed(sharedConnection)) {
            configureOrdinaryAutoCommit(sharedConnection);
            return sharedConnection;
        }
        closeSharedConnection();

        JdbcUrlCredentials urlCredentials = extractJdbcUrlCredentials(url);
        url = urlCredentials.url;
        Properties properties = new Properties();
        applyPhoenixUrlProperties(url, properties);
        String username = optionalText(connection, "username");
        String password = optionalText(connection, "password");
        if (username == null) {
            username = urlCredentials.username;
        }
        if (password == null) {

View on GitHub (pinned to c0390bff16)

Solutions

1. Add a valid JDBC URL to the connection config, e.g. "url": "jdbc:postgresql://host:5432/mydb".
2. If the plugin derives URLs from parts, fill in host, port, database (and vendor prefix option) so jdbcUrl() can construct the URL.
3. Check for typos in the connection key name (url vs jdbcUrl vs uri) against the plugin's expected field.
4. Log the parsed connection JSON before openConnection to confirm the field is present and non-empty at call time.

Example fix

// before
{ "connection": { "host": "db.internal", "port": 5432 } }
// after
{ "connection": { "url": "jdbc:postgresql://db.internal:5432/appdb" } }

// Java: validate connection config before calling the plugin
static void requireUrl(java.util.Map<String,Object> conn) {
    Object url = conn.get("url");
    if (url == null || url.toString().isBlank())
        throw new IllegalArgumentException("connection.url is required (jdbc:vendor://host:port/db)");
    if (!url.toString().startsWith("jdbc:"))
        throw new IllegalArgumentException("connection.url must start with jdbc:");
}

When it happens

Trigger: Calling any operation that opens a connection (handle, conn, genericTableObjectSource) with a connection object that omits the url field, or supplies only partial fields (host/port without database, or a url key with null/empty value) that jdbcUrl() cannot assemble.

Common situations: Saving a connection profile without the URL, a config migration renaming the url key, template placeholders left unexpanded (e.g. ${DB_URL} resolving to null), or constructing the JSON connection node programmatically and forgetting the field.

Related errors

• Agent runtime thread limits must be positive
• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)
• Unsupported H2 driver profile: " + profile
• is required.
• BENCH_CANDIDATES selected no candidates

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