pentaho/pentaho-kettle · error · KettleStepException

MergeRows.Exception.UnableToFindFieldInReferenceStream

MergeRows.Exception.UnableToFindFieldInReferenceStream

Error message

MergeRows.Exception.UnableToFindFieldInReferenceStream

What it means

Thrown by the Merge Rows step in processRow when a configured key field cannot be found in the reference stream's row metadata (indexOfValue returns < 0). The step resolves the indexes of meta.getKeyFields() in the reference (first) stream to perform the comparison.

Solutions

  1. Open the Merge Rows step dialog and correct the key field names against the reference stream's field list.
  2. Check the reference input step's output fields (Get Fields / Preview) for renamed or removed columns.
  3. Verify the correct step is connected as the reference (first) input; inputs are positional.
  4. Validate the transformation layout before execution to catch stale field references.

Example fix

// before (meta XML)
<key_field>cust_id</key_field>
// after (field was renamed upstream)
<key_field>customer_id</key_field>
Defensive patterns

Strategy: validation

Validate before calling

// Java: verify key fields exist in the reference stream
StepMeta mergeRows = transMeta.findStep("Merge Rows");
MergeRowsMeta meta = (MergeRowsMeta) mergeRows.getStepMetaInterface();
RowMetaInterface ref = transMeta.getPrevStepFields(mergeRows, 0);
for (String key : meta.getKeyFields()) {
  if (ref.indexOfValue(key) < 0) {
    throw new IllegalStateException("Key field missing in reference stream: " + key);
  }
}

Try / catch

try {
  trans.execute(null);
} catch (KettleStepException e) {
  if (e.getMessage().contains("UnableToFindFieldInReferenceStream")) {
    // correct Merge Rows key-field configuration
  }
}

Prevention

When it happens

Trigger: Running a transformation where an entry in the Merge Rows step's 'Key fields' list is not a field of the reference (first) input stream; this occurs in processRow before any rows are compared.

Common situations: Renaming or removing the key field in the reference branch; swapping the reference and compare inputs; typos in the key field name in the step dialog.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mergerows/MergeRows.java:106

      data.two = getRowFrom( data.twoRowSet );

      try {
        checkInputLayoutValid( data.oneRowSet.getRowMeta(), data.twoRowSet.getRowMeta() );
      } catch ( KettleRowException e ) {
        throw new KettleException( BaseMessages.getString( PKG, "MergeRows.Exception.InvalidLayoutDetected" ), e );
      }

      if ( data.one != null ) {
        // Find the key indexes:
        data.keyNrs = new int[ meta.getKeyFields().length ];
        for ( int i = 0; i < data.keyNrs.length; i++ ) {
          data.keyNrs[ i ] = data.oneRowSet.getRowMeta().indexOfValue( meta.getKeyFields()[ i ] );
          if ( data.keyNrs[ i ] < 0 ) {
            String message =
              BaseMessages.getString( PKG, "MergeRows.Exception.UnableToFindFieldInReferenceStream", meta
                .getKeyFields()[ i ] );
            logError( message );
            throw new KettleStepException( message );
          }
        }
      }

      if ( data.two != null ) {
        data.valueNrs = new int[ meta.getValueFields().length ];
        for ( int i = 0; i < data.valueNrs.length; i++ ) {
          data.valueNrs[ i ] = data.twoRowSet.getRowMeta().indexOfValue( meta.getValueFields()[ i ] );
          if ( data.valueNrs[ i ] < 0 ) {
            String message =
              BaseMessages.getString( PKG, "MergeRows.Exception.UnableToFindFieldInReferenceStream", meta
                .getValueFields()[ i ] );
            logError( message );
            throw new KettleStepException( message );
          }
        }
      }
    }

View on GitHub (pinned to f3058517a1)