pentaho/pentaho-kettle · error · KettleDatabaseException

Dynamic driver ' ' returned null for URL: — check that the…

Error message

Dynamic driver '{effectiveClassName}' returned null for URL: {url} — check that the URL format and driver class are correct.

What it means

Per the JDBC spec, Driver.connect may legally return null to signal 'this driver cannot connect to this URL'. PDI treats that null as a fatal, descriptive error because the driver already claimed to accept the URL, so a null is unexpected and usually indicates a wrong driver class or subtly wrong URL.

Solutions

  1. Confirm the driver class actually corresponds to the database in the URL
  2. Check the JDBC URL format against the vendor docs (prefix acceptance is shallower than connect)
  3. Supply required connection Properties (user, password, database name)
  4. Try a current, official driver JAR version

Example fix

// before
props = new Properties(); // no user/password -> driver returns null
// after
props.setProperty("user", "scott");
props.setProperty("password", "tiger");
Defensive patterns

Strategy: validation

Validate before calling

Properties p = new Properties();
p.setProperty("user", user); p.setProperty("password", pwd);
if (url == null || !url.startsWith("jdbc:")) throw new IllegalArgumentException("Malformed JDBC URL");

Try / catch

try { conn = db.getConnection(); } catch (KettleDatabaseException e) { if (e.getMessage().contains("returned null for URL")) { log.error("Driver silently refused URL — verify class/URL/properties: " + e.getMessage()); } else throw e; }

Prevention

When it happens

Trigger: connectUsingClass -> openConnectionViaDynamicDriver: localDriver.acceptsURL(url) returned true but localDriver.connect(url, properties) returned null — driver changed its mind due to URL details, properties mismatch, or a shim/wrapper driver that delegates to nothing.

Common situations: Driver class mismatch with the actual database (thin vs shim driver); URL accepted at prefix level but rejected on deeper validation; missing/incorrect connection properties the driver requires; stale/wrong driver version.

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/4e29895806acc136. Report an issue: GitHub.

Appendix: source

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

          + "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;
    } catch ( Exception e ) {
      throw new KettleDatabaseException(
        "Dynamic driver '" + effectiveClassName + "' failed to connect to URL '"
          + url + "': " + errorMsg( e ), e );
    }
  }

  /**
   * Returns the exception message, or the simple class name when the message is null.
   * Avoids repetitive inline ternary expressions in error-handling code.
   */
  private static String errorMsg( Exception e ) {

View on GitHub (pinned to f3058517a1)