pentaho/pentaho-kettle · error · KettleDatabaseException

Error occurred while trying to connect to the database

Error message

Error occurred while trying to connect to the database

What it means

normalConnect wraps any exception thrown while establishing the JDBC connection (driver load, DriverManager/connection creation, connect-time SQL statements) into KettleDatabaseException("Error occurred while trying to connect to the database", cause). The real failure reason is always in the cause chain.

Solutions

1. Read the wrapped cause exception for the actual root failure and fix accordingly
2. Verify host, port, database name, username and password in the DatabaseMeta
3. Ensure the JDBC driver jar is on the classpath or in the database plugin's lib directory
4. Test the connection from the same machine with a plain JDBC client to rule out network/firewall issues

Example fix

// before
db.connect(); // opaque message

// after
try {
  db.connect();
} catch ( KettleDatabaseException e ) {
  log.error( "Connect failed: " + e.getCause(), e );
}

// pre-check reachable endpoint before connect
InetSocketAddress addr = new InetSocketAddress( host, port );
if ( addr.isUnresolved() ) throw new IllegalStateException( "Unknown host " + host );

try {
  db.connect();
} catch ( KettleDatabaseException e ) {
  Throwable root = e.getCause();
  log.error( "DB connect failed: " + ( root != null ? root.getMessage() : e.getMessage() ), root );
}

When it happens

Trigger: Any Exception raised inside normalConnect's try block: driver class loading via connectUsingClass, SQLException from DriverManager, or exceptions from execStatements running connect-time SQL.

Common situations: Wrong host/port, database down, bad credentials, missing JDBC driver jar, invalid URL in DatabaseMeta, or failing connect-time SQL scripts.

Related errors

• An error occurred executing SQL:
• An error occurred executing SQL:
• Couldn't execute SQL:
• Couldn't find any rows because of an error :
• Couldn't get a result because of an error :

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

Appendix: source

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

        }
      } else {
        // using non-jndi and non-pooled connection -- just a simple JDBC
        connectUsingClass( databaseMeta.getDriverClass(), partitionId );
      }

      // See if we need to execute extra SQL statement...
      String sql = environmentSubstitute( databaseMeta.getConnectSQL() );

      // only execute if the SQL is not empty, null and is not just a bunch of
      // spaces, tabs, CR etc.
      if ( !Utils.isEmpty( sql ) && !Const.onlySpaces( sql ) ) {
        execStatements( sql );
        if ( log.isDetailed() ) {
          log.logDetailed( "Executed connect time SQL statements:" + Const.CR + sql );
        }
      }
    } catch ( Exception e ) {
      throw new KettleDatabaseException( "Error occurred while trying to connect to the database", e );
    }
  }

  public void initializeConnectionDataSource( String partitionId ) throws KettleDatabaseException {

    try {
      DataSourceProviderInterface dsp = DataSourceProviderFactory.getDataSourceProviderInterface();
      if ( dsp == null ) {
        // since DataSourceProviderFactory is initialised with new DatabaseUtil(),
        // this assignment is correct
        dsp = new DatabaseUtil();
      }

      if ( databaseMeta.getAccessType() == DatabaseMeta.TYPE_ACCESS_JNDI ) {
        this.dataSource = getJNDIDataSource( dsp );
      } else if ( databaseMeta.isUsingConnectionPool() ) {
        this.dataSource = getPoolingDataSource( partitionId, dsp );
      }

View on GitHub (pinned to f3058517a1)