pentaho/pentaho-kettle · error · KettleDatabaseException

Database.UnableToPreLoadConnectionToConnectionPool.Exception

Error message

Database.UnableToPreLoadConnectionToConnectionPool.Exception

What it means

ConnectionPoolUtil.testDataSource verifies a freshly created pool by calling ds.getConnection(); if that fails for any reason it throws 'Database.UnableToPreLoadConnectionToConnectionPool.Exception'. The pool was built but no physical connection could be obtained, so it's unusable.

Solutions

1. Check the chained cause (SQLException) for the exact driver error and fix URL/credentials accordingly
2. Verify the database server is running and reachable: telnet/nc host port
3. Ensure the JDBC driver jar is on the classpath / in lib/
4. Test the same connection parameters outside pooling (plain JDBC connect) to isolate pool config from connectivity

Example fix

// before
DatabaseMeta meta = new DatabaseMeta( "db", "POSTGRESQL", "Native", "dbhost", "mydb", "5555", "user", "pass" );
// after (correct host/port matching the running server)
DatabaseMeta meta = new DatabaseMeta( "db", "POSTGRESQL", "Native", "dbhost", "mydb", "5432", "user", "correctPass" );

// Pre-flight connectivity check before creating the pool
try ( Socket s = new Socket() ) { s.connect( new InetSocketAddress( dbMeta.getHostname(), Integer.parseInt( dbMeta.getDatabasePort() ) ), 5000 ); }
catch ( IOException e ) { throw new IllegalStateException( "Database host/port unreachable before pool creation", e ); }

boolean canReachDatabase( DatabaseMeta dbMeta ) { try ( Socket s = new Socket() ) { s.connect( new InetSocketAddress( dbMeta.getHostname(), Integer.parseInt( dbMeta.getDatabasePort() ) ), 3000 ); return true; } catch ( Exception e ) { return false; } }

try { ds = ConnectionPoolUtil.getDataSource( log, dbMeta, partitionId ); } catch ( KettleDatabaseException e ) { if ( isTransient( e ) ) { backoffAndRetry(); } else { throw new IllegalStateException( "Pool preload failed: " + e.getCause().getMessage(), e ); } }

When it happens

Trigger: addPoolableDataSource → testDataSource throws when ds.getConnection() fails: bad JDBC URL/credentials, database down or unreachable, driver class missing, pool exhausted, or listener/firewall blocking the port — all wrapped via the generic catch (Throwable e).

Common situations: Wrong hostname/port/db name in DatabaseMeta; invalid username/password; DB server stopped; JDBC driver jar not on classpath; TLS/SSL mismatch; network firewall dropping the connection.

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/789906d2dd5aee4a. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/ConnectionPoolUtil.java:292

    value = properties.getProperty( LOG_ABANDONED );
    if ( !Utils.isEmpty( value ) ) {
      ds.setLogAbandoned( Boolean.valueOf( value ) );
    }

  }

  /**
   * This method verifies that it's possible to get connection fron a datasource
   *
   * @param ds
   * @throws KettleDatabaseException
   */
  private static void testDataSource( DataSource ds ) throws KettleDatabaseException {
    Connection conn = null;
    try {
      conn = ds.getConnection();
    } catch ( Throwable e ) {
      throw new KettleDatabaseException( BaseMessages.getString( PKG,
          "Database.UnableToPreLoadConnectionToConnectionPool.Exception" ), e );
    } finally {
      DatabaseUtil.closeSilently( conn );
    }
  }

  /**
   * This methods adds a new data source to cache
   *
   * @param log
   * @param databaseMeta
   * @param partitionId
   * @param initialSize
   * @param maximumSize
   * @throws KettleDatabaseException
   */
  private static void addPoolableDataSource( LogChannelInterface log, DatabaseMeta databaseMeta, String partitionId,
      int initialSize, int maximumSize ) throws KettleDatabaseException {

View on GitHub (pinned to f3058517a1)