{"record":{"id":"ac4d72ea75ed6fec","repo":"pentaho/pentaho-kettle","slug":"throw-new-kettlestepexception-e-fuzzymatch","errorCode":null,"errorMessage":"throw new KettleStepException( e );","messagePattern":"throw new KettleStepException\\( e \\);","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatch.java","lineNumber":188,"sourceCode":"        getTransMeta().getBowl(), data.outputRowMeta, getStepname(), new RowMetaInterface[] { data.infoMeta }, null,\n        this, repository, metaStore );\n\n      // Check lookup field\n      data.indexOfMainField = getInputRowMeta().indexOfValue( environmentSubstitute( meta.getMainStreamField() ) );\n      if ( data.indexOfMainField < 0 ) {\n        // The field is unreachable !\n        throw new KettleException( BaseMessages.getString( PKG, \"FuzzyMatch.Exception.CouldnotFindMainField\", meta\n          .getMainStreamField() ) );\n      }\n    }\n    Object[] add = null;\n    if ( row[ data.indexOfMainField ] == null ) {\n      add = buildEmptyRow();\n    } else {\n      try {\n        add = getFromCache( row );\n      } catch ( Exception e ) {\n        throw new KettleStepException( e );\n      }\n    }\n    return RowDataUtil.addRowData( row, rowMeta.size(), add );\n  }\n\n  private void addToCache( Object[] value ) throws KettleException {\n    try {\n      data.look.add( value );\n    } catch ( java.lang.OutOfMemoryError o ) {\n      // exception out of memory\n      throw new KettleException( BaseMessages.getString( PKG, \"FuzzyMatch.Error.JavaHeap\", o.toString() ) );\n    }\n  }\n\n  private Object[] getFromCache( Object[] keyRow ) throws KettleValueException {\n    if ( isDebug() ) {\n      logDebug( BaseMessages.getString( PKG, \"FuzzyMatch.Log.ReadingMainStreamRow\", getInputRowMeta().getString(\n        keyRow ) ) );","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatch.java#L170-L206","documentation":"lookupValues calls getFromCache(row) to find the closest match for the main-stream row's key; any exception thrown inside cache lookup (including KettleExceptions from cached metadata or runtime conversions) is wrapped in a KettleStepException. It is a broad catch-all wrapping failure of the matching/caching path.","triggerScenarios":"row[indexOfMainField] is non-null but getFromCache throws — e.g. comparing the main value against cached lookup values fails due to incompatible value types, or an internal KettleException propagates from cache data structures.","commonSituations":"Main field and lookup field have mismatched types (String vs Number) making compareTo fail; cached lookup metadata was altered; unexpected null/typed data variations in the main field.","solutions":["Ensure the Main stream field and Lookup field have identical ValueMeta types (add a Select Values / type-conversion step to align them).","Read the wrapped cause of the KettleStepException (getMessage/getCause) to identify the underlying failure in getFromCache.","Normalize nulls/empty strings in the match key before the Fuzzy Match step.","Check that lookup stream rows loaded via readLookupValues match the expected cache schema."],"exampleFix":"// before (main field Integer vs lookup field String)\n// after: convert main field to String before Fuzzy Match\n// Select Values step: cust_id -> String\n// Fuzzy Match: Main stream field: cust_id (String), Lookup field: cust_id (String)","handlingStrategy":"validation","validationCode":"// Align types of main and lookup key fields before matching:\nValueMetaInterface main = mainRowMeta.searchValueMeta(mainField);\nValueMetaInterface look = lookupRowMeta.searchValueMeta(lookupField);\nif (main.getType() != look.getType()) {\n  throw new KettleException(\"Key type mismatch: \" + main + \" vs \" + look);\n}","typeGuard":"boolean keysCompatible(ValueMetaInterface a, ValueMetaInterface b) {\n  return a != null && b != null && a.getType() == b.getType();\n}","tryCatchPattern":"try {\n  add = getFromCache(row);\n} catch (KettleStepException e) {\n  logError(\"Fuzzy match cache lookup failed: \" + e.getCause(), e);\n  throw e; // rethrow after logging the wrapped cause\n}","preventionTips":["Make main and lookup key fields the same ValueMeta type before matching.","Handle null/empty keys explicitly before the Fuzzy Match step.","Log the cause chain of KettleStepException to find the real failure.","Test with representative data including edge-case values (nulls, long strings)."],"tags":["fuzzy-match","cache-lookup","type-mismatch"],"backgroundTag":"type-mismatch","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"}