pentaho/pentaho-kettle · error · KettleDatabaseException

Dynamic driver ' ' threw exception checking URL

Error message

Dynamic driver '{effectiveClassName}' threw exception checking URL '{url}': {errorMsg}

What it means

Before connecting, the dynamic driver's acceptsURL(url) is probed. If that call throws any Exception (driver bugs, classloading of driver internals, driver-level config parse errors), it is wrapped in this error with the driver class, URL, and cause message. It means the driver itself misbehaved while validating the URL, not that the URL was rejected.

Solutions

Inspect errorMsg(e) / the cause for the driver's internal failure
Fix the JDBC URL (remove unsupported or malformed parameters)
Check that the driver's dependency JARs were provided via extra JARs list
Try a different driver version known to handle your URL format

Example fix

// before
String url = "jdbc:postgresql://host:5432/db?sslmode=xyz"; // driver chokes on param
// after
String url = "jdbc:postgresql://host:5432/db?sslmode=require";

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-validate URL shape before connecting
if (!url.startsWith("jdbc:")) throw new IllegalArgumentException("URL must start with jdbc:");

Try / catch

try { conn = db.getConnection(); } catch (KettleDatabaseException e) { if (e.getMessage().contains("threw exception checking URL")) { log.error("Driver bug on acceptsURL: " + e.getCause(), e); } else throw e; }

Prevention

Keep JDBC URLs within documented parameter sets for the driver
Ship all driver dependency JARs so internal URL parsing doesn't NPE
Test the URL against the driver standalone before wiring into PDI
Pin known-good driver versions

When it happens

Trigger: connectUsingClass -> openConnectionViaDynamicDriver invokes localDriver.acceptsURL(url) and the driver implementation throws (e.g. its own sub-parser crashes, NPE in driver, missing driver dependency triggered during URL parse).

Common situations: Malformed URL that triggers a driver parsing bug; driver missing optional dependency jars needed during URL validation; broken driver version; exotic URL parameters the driver can't handle.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/12a42f352d6e30e0. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/Database.java:947

  }

  /**
   * Opens a JDBC connection via the already-loaded {@link #dynamicDriver}, bypassing
   * {@link DriverManager}. Validates URL acceptance before connecting.
   */
  private Connection openConnectionViaDynamicDriver( String effectiveClassName, String url, Properties properties )
    throws KettleDatabaseException {
    Driver localDriver = dynamicDriver.get();
    if ( localDriver == null ) {
      throw new KettleDatabaseException(
        "Dynamic driver for '" + effectiveClassName + "' has been unloaded (disconnect was called concurrently). "
          + "Reconnect to reload the driver." );
    }
    boolean accepts;
    try {
      accepts = localDriver.acceptsURL( url );
    } catch ( Exception e ) {
      throw new KettleDatabaseException(
        "Dynamic driver '" + effectiveClassName + "' threw exception checking URL '"
          + url + "': " + errorMsg( e ), e );
    }
    if ( !accepts ) {
      throw new KettleDatabaseException(
        "Dynamic driver '" + effectiveClassName + "' does not accept URL: " + url
          + " — check the JDBC URL format." );
    }
    try {
      Connection c = localDriver.connect( url, properties );
      if ( c == null ) {
        throw new KettleDatabaseException(
          "Dynamic driver '" + effectiveClassName + "' returned null for URL: " + url
            + " — check that the URL format and driver class are correct." );
      }
      return c;
    } catch ( KettleDatabaseException e ) {
      throw e;

View on GitHub (pinned to f3058517a1)