{"record":{"id":"80b56d48b9c60be8","repo":"pentaho/pentaho-kettle","slug":"dynamic-driver-failed-to-load-effectiveclassname-from","errorCode":null,"errorMessage":"Dynamic driver: failed to load '{effectiveClassName}' from '{resolvedPath}': {message}","messagePattern":"Dynamic driver: failed to load '(.+?)' from '(.+?)': (.+?)","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":925,"sourceCode":"    } else {\n      // No-cache path: fresh classloader and Driver per connection; closed on disconnect().\n      List<URL> urls = JdbcDriverResolver.buildUrlList( resolvedPath, extraJarPaths );\n      ChildFirstURLClassLoader loader = null;\n      try {\n        loader = new ChildFirstURLClassLoader( urls.toArray( new URL[ 0 ] ), Database.class.getClassLoader() );\n        Class<?> driverClass = loader.loadClass( effectiveClassName );\n        Driver driver = (Driver) driverClass.getDeclaredConstructor().newInstance();\n        dynamicDriver.set( driver );\n        dynamicDriverClassLoader.set( loader );\n      } catch ( Exception e ) {\n        if ( loader != null ) {\n          try {\n            loader.close();\n          } catch ( Exception ignored ) {\n            // best-effort\n          }\n        }\n        throw new KettleDatabaseException(\n          \"Dynamic driver: failed to load '\" + effectiveClassName + \"' from '\" + resolvedPath + \"': \" + e.getMessage(), e );\n      }\n    }\n  }\n\n  /**\n   * Opens a JDBC connection via the already-loaded {@link #dynamicDriver}, bypassing\n   * {@link DriverManager}. Validates URL acceptance before connecting.\n   */\n  private Connection openConnectionViaDynamicDriver( String effectiveClassName, String url, Properties properties )\n    throws KettleDatabaseException {\n    Driver localDriver = dynamicDriver.get();\n    if ( localDriver == null ) {\n      throw new KettleDatabaseException(\n        \"Dynamic driver for '\" + effectiveClassName + \"' has been unloaded (disconnect was called concurrently). \"\n          + \"Reconnect to reload the driver.\" );\n    }\n    boolean accepts;","sourceCodeStart":907,"sourceCodeEnd":943,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L907-L943","documentation":"Thrown when the URLClassLoader built from the resolved JAR cannot load/instantiate the driver class named effectiveClassName. The original exception (ClassNotFound, LinkageError, instantiation failure, etc.) is preserved as the cause and its message is embedded. The classloader is closed before throwing.","triggerScenarios":"connectUsingClass -> loadDynamicDriver: the resolved JAR exists and is a .jar, but Class.forName/newInstance inside the loader fails — class not present in that JAR, missing transitive dependency classes, wrong class name from the database plugin metadata, or conflicting class versions.","commonSituations":"effectiveClassName typo'd or from a different driver major version; driver JAR missing its dependency JARs (which should come via resolveAll of listDriverExtraJars); fat-thin driver mixup; JAR corrupted or built for a different Java version (UnsupportedClassVersionError).","solutions":["Read the cause: ClassNotFound => add the JAR containing the class or fix effectiveClassName; Linkage/Version errors => fix JAR/Java mismatch","Ensure all required extra JARs are listed in listDriverExtraJars so dependencies resolve","Verify the class name matches the driver inside the resolved JAR (unzip -l | grep Driver)","Re-download/verify the driver JAR if corrupted","Use the driver version matching your database server"],"exampleFix":"// before\nloadDynamicDriver(\"postgres\", \"org.postgresql.Driver9\", jars); // class doesn't exist in JAR\n// after\nloadDynamicDriver(\"postgres\", \"org.postgresql.Driver\", jars);","handlingStrategy":"validation","validationCode":"try (URLClassLoader l = new URLClassLoader(new URL[]{ new File(jarPath).toURI().toURL() }, getClass().getClassLoader())) {\n  Class<?> c = l.loadClass(effectiveClassName);\n  if (!java.sql.Driver.class.isAssignableFrom(c)) throw new IllegalStateException(effectiveClassName + \" is not a Driver in \" + jarPath);\n}","typeGuard":null,"tryCatchPattern":"try { db.connect(); } catch (KettleDatabaseException e) { if (e.getMessage().startsWith(\"Dynamic driver: failed to load\")) { log.error(\"Driver load failed: \" + e.getCause(), e); } else throw e; }","preventionTips":["Verify the class name against the JAR contents (unzip -l)","Include all driver dependency JARs in the extra-JARs list","Build/run on a JDK compatible with the driver's class-file version","Checksum driver JARs after download to catch corruption"],"tags":["jdbc","classpath","class-not-found","dynamic-driver"],"backgroundTag":"class-not-found","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"}