pentaho/pentaho-kettle · error · KettleConfigException

CombinationLookup.Log.UnexpectedError

Error message

CombinationLookup.Log.UnexpectedError

What it means

KettleConfigException thrown in preloadCache when preloading the cache is enabled but the hashRowMeta argument is null, meaning the row metadata needed to build the cache preload SQL is missing. The literal message is a localized key ('CombinationLookup.Log.UnexpectedError') from the messages bundle rather than descriptive text.

Solutions

  1. Open the CombinationLookup step and fill in the Key lookup fields (table fields used for hashing); hashRowMeta derives from them.
  2. Disable 'Preload cache' if you don't need it — the error only fires when preload is enabled.
  3. Re-save the transformation through the UI so the step metadata is regenerated cleanly.
  4. Check messages.properties for CombinationLookup.Log.UnexpectedError to see the localized description if needed.

Example fix

// before (ktr XML): <preload_cache>Y</preload_cache> with no keylookup entries
// after: either add <keylookup><field_name>...</field_name></keylookup> entries
//        or set <preload_cache>N</preload_cache>.
Defensive patterns

Strategy: validation

Validate before calling

// before running: ensure preload requires complete metadata
// if (meta.isPreloadCache() && (meta.getKeyLookup() == null || meta.getKeyLookup().length == 0))
//   throw new KettleException("Preload cache enabled but key lookup fields are empty");

Try / catch

try { /* run */ } catch (KettleConfigException e) {
  log.error("Preload cache misconfigured: hash row metadata missing; check key lookup fields");
}

Prevention

When it happens

Trigger: meta.getPreloadCache() is true and cacheSize >= 0, but processRow invoked preloadCache with hashRowMeta == null — the hash lookup row metadata was never built (e.g. key lookup fields absent).

Common situations: 'Preload cache' option enabled in the step while key lookup fields are empty/misconfigured; hand-edited transformation XML missing field definitions; metadata loaded from an older/foreign ktr version.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    super.dispose( smi, sdi );
  }

  /**
   * Preload the cache
   *
   * @param hashRowMeta The RowMeta of the hashRow
   * @throws KettleDatabaseException If something went wrong while selecting the values from the db
   * @throws KettleValueException    If something went wrong while adding the data to the cache
   * @throws KettleConfigException   If the step configuration is incomplete
   * @author nwyrwa
   */
  private void preloadCache( RowMetaInterface hashRowMeta )
    throws KettleDatabaseException, KettleValueException, KettleConfigException {
    // fast exit if no preload cache or no cache
    if ( meta.getPreloadCache() && meta.getCacheSize() >= 0 ) {
      if ( hashRowMeta == null ) {
        throw new KettleConfigException( BaseMessages.getString( PKG, "CombinationLookup.Log.UnexpectedError" ) );
      }
      DatabaseMeta databaseMeta = meta.getDatabaseMeta();
      if ( databaseMeta == null ) {
        throw new KettleConfigException( BaseMessages.getString( PKG, "CombinationLookup.Log.UnexpectedError" ) );
      }
      String lookupKeys = "";
      String sql = "";
      List<Object[]> cacheValues;

      /* build SQl Statement to preload cache
       *
           * SELECT
           * min(<retval>) as <retval>,
           * key1,
           * key2,
           * key3
           * FROM   <table>
           *

View on GitHub (pinned to f3058517a1)