{"record":{"id":"6791e1696f9cbc08","repo":"pentaho/pentaho-kettle","slug":"unable-to-register-delegating-driver-for-class","errorCode":null,"errorMessage":"Unable to register delegating driver for class {driverClassCanonicalName}","messagePattern":"Unable to register delegating driver for class (.+?)","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":670,"sourceCode":"      }\n    } catch ( NoClassDefFoundError | ClassNotFoundException e ) {\n      throw new KettleDatabaseException( BaseMessages.getString( PKG,\n        \"Database.Exception.UnableToFindClassMissingDriver\", classname, plugin.getName() ), e );\n    } catch ( Exception e ) {\n      throw new KettleDatabaseException( \"Exception while loading class\", e );\n    }\n  }\n\n  private void registerDelegatingDriver( Class<?> driverClass ) throws KettleDatabaseException {\n    String pluginId =\n      PluginRegistry.getInstance().getPluginId( DatabasePluginType.class, databaseMeta.getDatabaseInterface() );\n    Set<String> registeredDriversFromPlugin = registeredDrivers.computeIfAbsent( pluginId, k -> new HashSet<>() );\n    // Prevent registering multiple delegating drivers for same class, plugin\n    if ( !registeredDriversFromPlugin.contains( driverClass.getCanonicalName() ) ) {\n      try {\n        DriverManager.registerDriver( new DelegatingDriver( (Driver) driverClass.getDeclaredConstructor().newInstance() ) );\n      } catch ( InstantiationException | IllegalAccessException | NoSuchMethodException | java.lang.reflect.InvocationTargetException | SQLException e ) {\n        throw new KettleDatabaseException(\n          \"Unable to register delegating driver for class \" + driverClass.getCanonicalName(), e );\n      }\n      registeredDriversFromPlugin.add( driverClass.getCanonicalName() );\n    }\n  }\n\n  private String resolveUrl( String partitionId ) throws KettleDatabaseException {\n    if ( databaseMeta.isPartitioned() && !Utils.isEmpty( partitionId ) ) {\n      return environmentSubstitute( databaseMeta.getURL( partitionId ) );\n    }\n    return environmentSubstitute( databaseMeta.getURL() );\n  }\n\n  private String[] resolveCredentials( String partitionId ) {\n    if ( databaseMeta.isPartitioned() && !Utils.isEmpty( partitionId ) ) {\n      PartitionDatabaseMeta partition = databaseMeta.getPartitionMeta( partitionId );\n      if ( partition != null && !Utils.isEmpty( partition.getUsername() ) ) {\n        return new String[] { partition.getUsername(),","sourceCodeStart":652,"sourceCodeEnd":688,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L652-L688","documentation":"Thrown by Database.registerDelegatingDriver when instantiating a JDBC driver class and registering a DelegatingDriver wrapper with DriverManager fails. Any of ClassNotFoundException-driven instantiation problems ( reflective construction ) or SQLException during registration results in this KettleDatabaseException. The class was found but could not be turned into a live registered driver.","triggerScenarios":"loadStaticDriver calls registerDelegatingDriver for a plugin's driver class; the driver class has no no-arg constructor, the constructor throws, the class is abstract/interface, access is denied, or DriverManager.registerDriver throws SQLException (e.g. driver already registered incompatibly).","commonSituations":"Driver JAR present but class is not a valid java.sql.Driver; driver class loaded by the wrong classloader so newInstance fails; duplicate plugin registrations racing; a broken/incompatible driver version in the plugin folder.","solutions":["Verify the configured driver class has a public no-arg constructor and implements java.sql.Driver","Check the full cause chain (InstantiationException/NoSuchMethodException/SQLException) to identify the exact failure","Ensure the driver JAR matches the driver class name/version expected by the database plugin","Remove duplicate or stale driver JARs from the plugin's lib directory","Check that no SecurityManager/classloader policy blocks reflective instantiation"],"exampleFix":"// before (broken driver class)\nClass.forName(\"com.broken.Driver\") // compiles, but no public no-arg ctor\n// after\n// use the vendor's documented driver class, e.g.\nString cls = \"org.postgresql.Driver\"; // has public no-arg ctor and implements java.sql.Driver","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(driverClassName, true, loader);\nif (!java.sql.Driver.class.isAssignableFrom(c)) throw new IllegalStateException(driverClassName + \" is not a java.sql.Driver\");\nc.getDeclaredConstructor().setAccessible(true); // throws NoSuchMethodException early if missing","typeGuard":"boolean isValidDriverClass(Class<?> c) { return c != null && java.sql.Driver.class.isAssignableFrom(c); }","tryCatchPattern":"try { db.connect(); } catch (KettleDatabaseException e) { if (e.getMessage().startsWith(\"Unable to register delegating driver\")) { log.error(\"Driver JAR/class invalid: \" + e.getCause(), e); } else throw e; }","preventionTips":["Always ship official vendor driver JARs","Verify driver classes implement java.sql.Driver before configuring plugins","Keep only one version of each driver JAR in the plugin lib folder","Read the root cause chain, not just the wrapper message"],"tags":["jdbc","database","driver-registration","reflection"],"backgroundTag":"module-init-failed","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"}