pentaho/pentaho-kettle · error · KettleDatabaseException

Unable to prepare combi-lookup statement

Error message

Unable to prepare combi-lookup statement

What it means

setCombiLookup builds the SQL to look up an existing junk-dimension key and prepares a JDBC PreparedStatement. Any SQLException during prepare (or setMaxRows) is wrapped in a KettleDatabaseException 'Unable to prepare combi-lookup statement'.

Solutions

1. Check the nested SQLException for the real database message
2. Verify the dimension table, schema and columns exist and are SELECT-able by the DB user
3. Test the database connection in the transformation's DB metadata (Test button)
4. Confirm the database dialect matches the actual server

// Verify the junk dimension table exists before running
Database db = new Database(parent, databaseMeta);
db.connect();
if (!db.checkTableExists(schemaTable)) {
  throw new IllegalStateException("Junk dimension table missing: " + schemaTable);
}
db.disconnect();

try {
  trans.execute(null);
  trans.waitUntilFinished();
} catch (KettleDatabaseException e) {
  Throwable root = e; while (root.getCause() != null) root = root.getCause();
  log.error("Combi-lookup prepare failed: " + root.getMessage(), root);
  if (root instanceof java.sql.SQLRecoverableException) { /* reconnect and retry */ }
}

When it happens

Trigger: data.db.getConnection().prepareStatement(sql) throws — invalid SQL against the target database (bad table/column names in the junk dimension), wrong database type, or closed/broken connection.

Common situations: Junk dimension table deleted or renamed in the DB; wrong schema; database user lacking SELECT privilege; connection dropped before the first row; unsupported DB dialect producing invalid SQL.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• Unable to prepare combi insert statement : + Const.CR +…
• 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/98f4a9fc5faced2a. Report an issue: GitHub.

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/combinationlookup/CombinationLookup.java:468

      }
      // Add the ValueMeta for the null check, BUT cloning needed.
      // Otherwise the field gets renamed and gives problems when referenced by previous steps.
      data.lookupRowMeta.addValueMeta( inputRowMeta.getValueMeta( data.keynrs[ i ] ).clone() );

      sql += " ) )";
      sql += Const.CR;
    }

    try {
      if ( log.isDebug() ) {
        logDebug( "preparing combi-lookup statement:" + Const.CR + sql );
      }
      data.prepStatementLookup = data.db.getConnection().prepareStatement( databaseMeta.stripCR( sql ) );
      if ( databaseMeta.supportsSetMaxRows() ) {
        data.prepStatementLookup.setMaxRows( 1 ); // alywas get only 1 line back!
      }
    } catch ( SQLException ex ) {
      throw new KettleDatabaseException( "Unable to prepare combi-lookup statement", ex );
    }
  }

  /**
   * This inserts new record into a junk dimension
   */
  public Long combiInsert( RowMetaInterface rowMeta, Object[] row, Long val_key, Long val_crc )
    throws KettleDatabaseException {
    String debug = "Combination insert";
    DatabaseMeta databaseMeta = meta.getDatabaseMeta();
    try {
      if ( data.prepStatementInsert == null ) { // first time: construct prepared statement
        debug = "First: construct prepared statement";

        data.insertRowMeta = new RowMeta();

        /*
         * Construct the SQL statement...

View on GitHub (pinned to f3058517a1)