{"record":{"id":"789906d2dd5aee4a","repo":"pentaho/pentaho-kettle","slug":"database-unabletopreloadconnectiontoconnectionpool-exception","errorCode":null,"errorMessage":"Database.UnableToPreLoadConnectionToConnectionPool.Exception","messagePattern":"Database\\.UnableToPreLoadConnectionToConnectionPool\\.Exception","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/ConnectionPoolUtil.java","lineNumber":292,"sourceCode":"    value = properties.getProperty( LOG_ABANDONED );\n    if ( !Utils.isEmpty( value ) ) {\n      ds.setLogAbandoned( Boolean.valueOf( value ) );\n    }\n\n  }\n\n  /**\n   * This method verifies that it's possible to get connection fron a datasource\n   *\n   * @param ds\n   * @throws KettleDatabaseException\n   */\n  private static void testDataSource( DataSource ds ) throws KettleDatabaseException {\n    Connection conn = null;\n    try {\n      conn = ds.getConnection();\n    } catch ( Throwable e ) {\n      throw new KettleDatabaseException( BaseMessages.getString( PKG,\n          \"Database.UnableToPreLoadConnectionToConnectionPool.Exception\" ), e );\n    } finally {\n      DatabaseUtil.closeSilently( conn );\n    }\n  }\n\n  /**\n   * This methods adds a new data source to cache\n   *\n   * @param log\n   * @param databaseMeta\n   * @param partitionId\n   * @param initialSize\n   * @param maximumSize\n   * @throws KettleDatabaseException\n   */\n  private static void addPoolableDataSource( LogChannelInterface log, DatabaseMeta databaseMeta, String partitionId,\n      int initialSize, int maximumSize ) throws KettleDatabaseException {","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/ConnectionPoolUtil.java#L274-L310","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the chained cause (SQLException) for the exact driver error and fix URL/credentials accordingly","Verify the database server is running and reachable: telnet/nc host port","Ensure the JDBC driver jar is on the classpath / in lib/","Test the same connection parameters outside pooling (plain JDBC connect) to isolate pool config from connectivity"],"exampleFix":"// before\nDatabaseMeta meta = new DatabaseMeta( \"db\", \"POSTGRESQL\", \"Native\", \"dbhost\", \"mydb\", \"5555\", \"user\", \"pass\" );\n// after (correct host/port matching the running server)\nDatabaseMeta meta = new DatabaseMeta( \"db\", \"POSTGRESQL\", \"Native\", \"dbhost\", \"mydb\", \"5432\", \"user\", \"correctPass\" );","handlingStrategy":"retry","validationCode":"// Pre-flight connectivity check before creating the pool\ntry ( Socket s = new Socket() ) { s.connect( new InetSocketAddress( dbMeta.getHostname(), Integer.parseInt( dbMeta.getDatabasePort() ) ), 5000 ); }\ncatch ( IOException e ) { throw new IllegalStateException( \"Database host/port unreachable before pool creation\", e ); }","typeGuard":"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; } }","tryCatchPattern":"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 ); } }","preventionTips":["Verify hostname, port, database name, and credentials in DatabaseMeta before pooling","Ensure the JDBC driver jar is present on the classpath","Monitor database availability; pool creation fails immediately when the server is down","Retry only transient causes (connection timeouts), fail fast on auth/URL errors"],"tags":["connection-pool","jdbc","connectivity"],"backgroundTag":"connection-refused","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"}