{"record":{"id":"69c3b3860b376bfe","repo":"pentaho/pentaho-kettle","slug":"combinationlookup-log-unexpectederror","errorCode":null,"errorMessage":"CombinationLookup.Log.UnexpectedError","messagePattern":"CombinationLookup\\.Log\\.UnexpectedError","errorType":"exception","errorClass":"KettleConfigException","httpStatus":null,"severity":"error","filePath":"plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/combinationlookup/CombinationLookup.java","lineNumber":713,"sourceCode":"\n    super.dispose( smi, sdi );\n  }\n\n  /**\n   * Preload the cache\n   *\n   * @param hashRowMeta The RowMeta of the hashRow\n   * @throws KettleDatabaseException If something went wrong while selecting the values from the db\n   * @throws KettleValueException    If something went wrong while adding the data to the cache\n   * @throws KettleConfigException   If the step configuration is incomplete\n   * @author nwyrwa\n   */\n  private void preloadCache( RowMetaInterface hashRowMeta )\n    throws KettleDatabaseException, KettleValueException, KettleConfigException {\n    // fast exit if no preload cache or no cache\n    if ( meta.getPreloadCache() && meta.getCacheSize() >= 0 ) {\n      if ( hashRowMeta == null ) {\n        throw new KettleConfigException( BaseMessages.getString( PKG, \"CombinationLookup.Log.UnexpectedError\" ) );\n      }\n      DatabaseMeta databaseMeta = meta.getDatabaseMeta();\n      if ( databaseMeta == null ) {\n        throw new KettleConfigException( BaseMessages.getString( PKG, \"CombinationLookup.Log.UnexpectedError\" ) );\n      }\n      String lookupKeys = \"\";\n      String sql = \"\";\n      List<Object[]> cacheValues;\n\n      /* build SQl Statement to preload cache\n       *\n           * SELECT\n           * min(<retval>) as <retval>,\n           * key1,\n           * key2,\n           * key3\n           * FROM   <table>\n           *","sourceCodeStart":695,"sourceCodeEnd":731,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/combinationlookup/CombinationLookup.java#L695-L731","documentation":"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.","triggerScenarios":"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).","commonSituations":"'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.","solutions":["Open the CombinationLookup step and fill in the Key lookup fields (table fields used for hashing); hashRowMeta derives from them.","Disable 'Preload cache' if you don't need it — the error only fires when preload is enabled.","Re-save the transformation through the UI so the step metadata is regenerated cleanly.","Check messages.properties for CombinationLookup.Log.UnexpectedError to see the localized description if needed."],"exampleFix":"// before (ktr XML): <preload_cache>Y</preload_cache> with no keylookup entries\n// after: either add <keylookup><field_name>...</field_name></keylookup> entries\n//        or set <preload_cache>N</preload_cache>.","handlingStrategy":"validation","validationCode":"// before running: ensure preload requires complete metadata\n// if (meta.isPreloadCache() && (meta.getKeyLookup() == null || meta.getKeyLookup().length == 0))\n//   throw new KettleException(\"Preload cache enabled but key lookup fields are empty\");","typeGuard":null,"tryCatchPattern":"try { /* run */ } catch (KettleConfigException e) {\n  log.error(\"Preload cache misconfigured: hash row metadata missing; check key lookup fields\");\n}","preventionTips":["Only enable Preload cache after key lookup fields are configured.","Validate transformations after merging/importing ktr XML.","Re-save steps through the Spoon UI to regenerate metadata."],"tags":["configuration","cache","metadata","kettle"],"backgroundTag":"missing-required-config-field","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"}