pentaho/pentaho-kettle · error · KettleStepException

StreamLookupMeta.Exception.ReturnValueCanNotBeFound

Error message

StreamLookupMeta.Exception.ReturnValueCanNotBeFound

What it means

In StreamLookupMeta.getFields, when the lookup value's ValueMeta cannot be found (the configured return field does not exist in the lookup stream's metadata), the step throws ReturnValueCanNotBeFound. This is configuration-time field resolution: the step cannot add the return field to the output row because the source metadata is missing.

Solutions

1. Open the StreamLookup step, press 'Get lookup fields', and re-select the return fields from the actual lookup stream
2. Ensure the hop from the source step to the lookup input exists so its field metadata is available
3. Correct the <value> field name in the step metadata / ktr XML
4. Fix the upstream step so it actually emits the configured return field

Example fix

// before
<value>amount_toto</value>
// after
<value>amount_total</value>

// Before getFields, verify each return field exists in the info stream metadata
for (String v : meta.getValue()) {
  if (infoRowMeta.searchValueMeta(v) == null)
    throw new IllegalStateException("Return field not found in lookup stream: " + v);
}

boolean returnFieldsExist(RowMetaInterface infoMeta, String[] values) {
  return infoMeta != null && Arrays.stream(values)
    .allMatch(v -> infoMeta.searchValueMeta(v) != null);
}

try { meta.getFields(inputRowMeta, origin, infoRowMeta, ...); }
catch (KettleStepException e) {
  if (e.getMessage().contains("ReturnValueCanNotBeFound")) { /* refresh step metadata */ }
  throw e;
}

When it happens

Trigger: getFields looks up getValue()[i] in the info stream's row metadata; v == null triggers the throw because the return field doesn't exist in the lookup stream.

Common situations: Value field renamed/deleted upstream after configuration; hop order changed so getFields runs before the source step's fields are known; typo in the return field name; transformation metadata not refreshed (no hop connections defined when getFields runs).

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• StreamLookup.Exception.UnableToFindField
• StreamLookup.Log.FieldNotFound
• ColumnExists.Exception.CouldnotFindField
• CombinationLookup.Exception.FieldNotFound
• Error converting data while looking up value

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/streamlookup/StreamLookupMeta.java:224

    setUsingSortedList( false );
    setUsingIntegerPair( false );

    allocate( 0, 0 );
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface row, String origin, RowMetaInterface[] info, StepMeta nextStep,
    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {
    if ( info != null && info.length == 1 && info[0] != null ) {
      for ( int i = 0; i < getValueName().length; i++ ) {
        ValueMetaInterface v = info[0].searchValueMeta( getValue()[i] );
        if ( v != null ) {
          // Configuration error/missing resources...
          v.setName( getValueName()[i] );
          v.setOrigin( origin );
          row.addValueMeta( v );
        } else {
          throw new KettleStepException( BaseMessages.getString( PKG,
              "StreamLookupMeta.Exception.ReturnValueCanNotBeFound", getValue()[i] ) );
        }
      }
    } else {
      for ( int i = 0; i < getValueName().length; i++ ) {
        try {
          ValueMetaInterface v = ValueMetaFactory.createValueMeta( getValueName()[i], getValueDefaultType()[i] );
          v.setOrigin( origin );
          row.addValueMeta( v );
        } catch ( Exception e ) {
          throw new KettleStepException( e );
        }
      }
    }
  }

  @Override
  public String getXML() {

View on GitHub (pinned to f3058517a1)