pentaho/pentaho-kettle · error · KettleDatabaseException

Database.Exception.ConnectionTestFailed

Error message

Database.Exception.ConnectionTestFailed

What it means

connectUsingClass translates SQLExceptions thrown while acquiring the JDBC connection via the database plugin's driver class into KettleDatabaseException with the i18n message "Database.Exception.ConnectionTestFailed" (parameterized with the database description). It signals the driver was loaded but the connection itself was refused/failed.

Solutions

1. Read the wrapped SQLException (cause) for the vendor error code and message
2. Validate host, port, database name, user and password in the connection dialog/DatabaseMeta
3. Test network reachability (ping/telnet to host:port) from the running host
4. Check account status and SSL/TLS requirements on the database server

Example fix

// before
url = "jdbc:mysql://localhost"; // missing db/port

// after
url = "jdbc:mysql://localhost:3306/mydb?useSSL=true";

// pre-connect probe
try ( Socket s = new Socket() ) {
  s.connect( new InetSocketAddress( host, port ), 3000 ); // throws if unreachable
}

try {
  db.connect();
} catch ( KettleDatabaseException e ) {
  SQLException sql = findCauseOfType( e, SQLException.class );
  if ( sql != null && isTransient( sql.getErrorCode() ) ) retryConnect( db );
  else log.error( "Connection test failed: " + sql, sql );
}

When it happens

Trigger: SQLException from dataSource.getConnection/DriverManager.getConnection in connectUsingClass — bad credentials, unreachable server, unknown database, SSL handshake failure, or connection pool exhaustion.

Common situations: Typos in host/port/db name, database server down or firewalled, expired/locked DB account, TLS misconfiguration, wrong driver/URL combination for the database type.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• AccessInputMeta.Exception.ErrorSavingToRepository
• An error occurred executing SQL:
• An error occurred executing SQL:
• Cannot fetch driver metadata for
• Couldn't close query: resultset or prepared statements

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

Appendix: source

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

      loadStaticDriver( classname, plugin );
    }

    try {
      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 );

View on GitHub (pinned to f3058517a1)