What causes "FuzzyMatchMeta.Exception.ReturnValueCanNotBeFound" in pentaho/pentaho-kettle?

Open the FuzzyMatch step dialog and re-select the return values so they match fields actually present in the lookup stream

pentaho/pentaho-kettle · error · KettleStepException

FuzzyMatchMeta.Exception.ReturnValueCanNotBeFound

Error message

FuzzyMatchMeta.Exception.ReturnValueCanNotBeFound

What it means

In getFields(), after the transformation is configured the step maps each configured return value name (value[i]) to a field produced by the lookup stream; if the requested return field cannot be found in the lookup row meta, it throws KettleStepException 'FuzzyMatchMeta.Exception.ReturnValueCanNotBeFound' with the missing field name.

Solutions

Open the FuzzyMatch step dialog and re-select the return values so they match fields actually present in the lookup stream
Verify the upstream lookup transform still produces the missing field (name and case)
Refresh field metadata in Spoon (right-click step > 'Update fields' or re-run 'Get Fields')
Rename the return value in the step config to the new field name

Example fix

// before (step meta references a removed field)
value[0] = "customer_name_old"
// after
value[0] = "customer_name"  // matches a field in the lookup stream

Defensive patterns

Strategy: validation

Validate before calling

RowMetaInterface lookupFields = lookupTransform.getOutputRowMeta();
for (String returnField : stepMeta.getReturnValueNames()) {
  if (lookupFields.searchValueMeta(returnField) == null) {
    throw new IllegalStateException("FuzzyMatch return value not in lookup stream: " + returnField);
  }
}

Try / catch

try {
  stepMeta.getStepMetaInterface().getFields(inputRowMeta, origin, info, targetStepMeta, metaStore, space);
} catch (KettleStepException e) {
  if (e.getMessage() != null && e.getMessage().contains("ReturnValueCanNotBeFound")) {
    // re-open the step dialog and re-select return values to match the lookup stream
  } else throw e;
}

Prevention

After changing upstream lookup transform fields, always re-open FuzzyMatch and refresh return values
Avoid renaming fields consumed by FuzzyMatch without updating the step
Use consistent field name casing across transforms
Run transformation metadata validation before production execution

When it happens

Trigger: getFields(inputRowMeta, ...) is called with a 'value' entry that has no matching ValueMetaInterface in the lookup input row meta (the inner branch), typically because the lookup stream no longer contains that field.

Common situations: Renaming or deleting a column in the lookup transform after configuring FuzzyMatch return values; passing a lookup stream whose field names changed case; copy-pasting steps between transformations with different schemas.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatchMeta.java:495

      isGetCloserValue()
        || ( getAlgorithmType() == FuzzyMatchMeta.OPERATION_TYPE_DOUBLE_METAPHONE )
        || ( getAlgorithmType() == FuzzyMatchMeta.OPERATION_TYPE_SOUNDEX )
        || ( getAlgorithmType() == FuzzyMatchMeta.OPERATION_TYPE_REFINED_SOUNDEX )
        || ( getAlgorithmType() == FuzzyMatchMeta.OPERATION_TYPE_METAPHONE );

    if ( activateAdditionalFields ) {
      if ( info != null && info.length == 1 && info[0] != null ) {
        for ( int i = 0; i < valueName.length; i++ ) {
          v = info[0].searchValueMeta( value[i] );
          if ( v != null ) {
            // Configuration error/missing resources...

            v.setName( valueName[i] );
            v.setOrigin( name );
            v.setStorageType( ValueMetaInterface.STORAGE_TYPE_NORMAL ); // Only normal storage goes into the cache
            inputRowMeta.addValueMeta( v );
          } else {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "FuzzyMatchMeta.Exception.ReturnValueCanNotBeFound", value[i] ) );
          }
        }
      } else {
        for ( int i = 0; i < valueName.length; i++ ) {
          v = new ValueMetaString( valueName[i] );
          v.setOrigin( name );
          inputRowMeta.addValueMeta( v );
        }
      }
    }
  }

  public String getXML() {
    StringBuilder retval = new StringBuilder();

    StreamInterface infoStream = getStepIOMeta().getInfoStreams().get( 0 );
    retval.append( "    " + XMLHandler.addTagValue( "from", infoStream.getStepname() ) );

View on GitHub (pinned to f3058517a1)