What causes "Error connecting to database: (using class {classname})" in pentaho/pentaho-kettle?

Inspect the cause for the concrete non-SQL exception

pentaho/pentaho-kettle · error · KettleDatabaseException

Error connecting to database

Error message

Error connecting to database: (using class {classname})

What it means

connectUsingClass's generic catch (Exception) wraps any non-SQL failure during connection creation into KettleDatabaseException("Error connecting to database: (using class <classname>)"). This covers everything other than SQLException — e.g. driver API mismatches, initialization errors inside the driver, or runtime exceptions from the database plugin class.

Solutions

Inspect the cause for the concrete non-SQL exception
Confirm the driver jar version is compatible with both the database server and the Kettle plugin
Verify the custom driver class name in DatabaseMeta is the correct one for that jar
Re-deploy the driver plugin to rule out a corrupted installation

Example fix

// before
customDriverClass = "com.mysql.jdbc.Driver"; // legacy driver with newer connector

// after
customDriverClass = "com.mysql.cj.jdbc.Driver"; // matches Connector/J 8.x

Defensive patterns

Strategy: try-catch

Validate before calling

try {
  Class.forName( classname ); // verify driver loads before connectUsingClass
} catch ( Throwable t ) {
  log.error( "Driver class " + classname + " cannot be initialized", t );
}

Try / catch

try {
  db.connect();
} catch ( KettleDatabaseException e ) {
  if ( e.getMessage().startsWith( "Error connecting to database: (using class" ) ) {
    log.error( "Non-SQL driver failure for " + classname + ": " + e.getCause(), e.getCause() );
  }
}

Prevention

Pin driver versions compatible with the server and the Kettle plugin
Avoid mixing multiple versions of the same driver on the classpath
Test driver loading in isolation when introducing new database types

When it happens

Trigger: A non-SQLException thrown while loading/initializing the driver class or obtaining the connection through the plugin's DatabaseInterface: ClassCastException, AbstractMethodError-like wrapper exceptions, or driver constructor/init failures.

Common situations: Driver version incompatible with the plugin interface (e.g. JDBC 4 driver with old code paths), corrupted driver jar, wrong driver class configured for the database type, security manager or OSGi classloading restrictions.

Related errors

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

Appendix: source

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

      String url = resolveUrl( partitionId );
      String[] credentials = resolveCredentials( partitionId );
      url = applyCredentialsToProperties( url, credentials[0], credentials[1], properties );

      log.logDetailed( "Acquiring JDBC connection for database [" + databaseMeta.getName() + "] using driver class [" + classname + "]..." );
      long startJdbc = System.currentTimeMillis();
      if ( usingDynamicDriver ) {
        connection = openConnectionViaDynamicDriver( jdbcDriverClass, url, properties );
      } else {
        connection = DriverManager.getConnection( url, properties );
      }
      log.logDetailed( "JDBC connection acquired for database [" + databaseMeta.getName() + "] in " + ( System.currentTimeMillis() - startJdbc ) + " ms" );
    } catch ( SQLException sqlException ) {
      closeDynamicClassLoader();
      throw new KettleDatabaseException(
        BaseMessages.getString( PKG, "Database.Exception.ConnectionTestFailed", toString() ), sqlException );
    } catch ( Exception e ) {
      closeDynamicClassLoader();
      throw new KettleDatabaseException( "Error connecting to database: (using class " + classname + ")", e );
    }
  }

  private void loadStaticDriver( String classname, PluginInterface plugin ) throws KettleDatabaseException {
    try {
      synchronized ( java.sql.DriverManager.class ) {
        ClassLoader classLoader = PluginRegistry.getInstance().getClassLoader( plugin );
        Class<?> driverClass = classLoader.loadClass( classname );
        // Only need DelegatingDriver for drivers not from our classloader
        if ( driverClass.getClassLoader() != this.getClass().getClassLoader() ) {
          registerDelegatingDriver( driverClass );
        } else {
          // Trigger static register block in driver class
          Class.forName( classname );
        }
      }
    } catch ( NoClassDefFoundError | ClassNotFoundException e ) {
      throw new KettleDatabaseException( BaseMessages.getString( PKG,

View on GitHub (pinned to f3058517a1)