{"record":{"id":"e4aa834748b0efe5","repo":"pentaho/pentaho-kettle","slug":"dynamic-driver-effectiveclassname-failed-to-connect-to-url","errorCode":null,"errorMessage":"Dynamic driver '{effectiveClassName}' failed to connect to URL '{url}': {errorMsg}","messagePattern":"Dynamic driver '(.+?)' failed to connect to URL '(.+?)': (.+?)","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":967,"sourceCode":"          + url + \"': \" + errorMsg( e ), e );\n    }\n    if ( !accepts ) {\n      throw new KettleDatabaseException(\n        \"Dynamic driver '\" + effectiveClassName + \"' does not accept URL: \" + url\n          + \" — check the JDBC URL format.\" );\n    }\n    try {\n      Connection c = localDriver.connect( url, properties );\n      if ( c == null ) {\n        throw new KettleDatabaseException(\n          \"Dynamic driver '\" + effectiveClassName + \"' returned null for URL: \" + url\n            + \" — check that the URL format and driver class are correct.\" );\n      }\n      return c;\n    } catch ( KettleDatabaseException e ) {\n      throw e;\n    } catch ( Exception e ) {\n      throw new KettleDatabaseException(\n        \"Dynamic driver '\" + effectiveClassName + \"' failed to connect to URL '\"\n          + url + \"': \" + errorMsg( e ), e );\n    }\n  }\n\n  /**\n   * Returns the exception message, or the simple class name when the message is null.\n   * Avoids repetitive inline ternary expressions in error-handling code.\n   */\n  private static String errorMsg( Exception e ) {\n    return e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();\n  }\n\n\n  @Override\n  public void close() {\n    disconnect();\n  }","sourceCodeStart":949,"sourceCodeEnd":985,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L949-L985","documentation":"KettleDatabaseException thrown by Database.connect() when a dynamically loaded JDBC driver class fails to open a connection to the given URL. It wraps the underlying driver exception (errorMsg(e)) so the root cause (bad URL, driver mismatch, network, auth) is preserved. It only fires on the dynamic-driver code path after the class was loaded but DriverManager.getConnection failed.","triggerScenarios":"Calling Database.connect() (or connectAnon) where databaseMeta uses a dynamic/plugin driver: the driver class loaded but DriverManager.getConnection(url, props) threw — wrong JDBC URL format, driver does not accept the URL scheme, DB down/unreachable, or bad credentials.","commonSituations":"Typo in the JDBC URL (jdbc:mysql:// vs jdbc:postgresql://), wrong port, firewall/DNS failure, database stopped, driver jar version incompatible with the URL syntax, or special characters in password not escaped.","solutions":["Verify the JDBC URL format against the driver's documentation and correct databaseMeta URL/hostname/port/database","Confirm the DB server is running and reachable (ping/telnet host port)","Check username/password are correct for the target database","Verify the driver jar version supports the URL syntax being used; upgrade or correct the driver plugin","Inspect the wrapped cause exception (getCause()) for the driver's own error message"],"exampleFix":"// before\ndatabaseMeta.setURL(\"jdbc:mysql//host:3306/db\");\n// after\ndatabaseMeta.setURL(\"jdbc:mysql://host:3306/db\");","handlingStrategy":"try-catch","validationCode":"String url = databaseMeta.getURL();\nif ( url == null || !url.startsWith( \"jdbc:\" ) ) {\n  throw new IllegalArgumentException( \"Invalid JDBC URL: \" + url );\n}","typeGuard":"boolean isValidJdbcUrl( String url ) {\n  return url != null && url.matches( \"jdbc:[a-zA-Z0-9]+://.+\" );\n}","tryCatchPattern":"try {\n  database.connect();\n} catch ( KettleDatabaseException e ) {\n  Throwable cause = e.getCause();\n  log.error( \"Driver connect failed: \" + cause.getMessage(), cause );\n  throw new RuntimeException( \"Check JDBC URL, driver and DB availability\", e );\n}","preventionTips":["Validate the JDBC URL format against driver docs before connecting","Health-check DB host/port (telnet) before starting the transformation","Pin a driver version known to work with the URL syntax","Log getCause() to surface the driver's real error"],"tags":["jdbc","database","connection","dynamic-driver"],"backgroundTag":"connection-refused","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}