pentaho/pentaho-kettle · error · KettleStepException

Unable to find field

Error message

Unable to find field [{0}] in the input rows

What it means

KettleStepException thrown by RowMetaUtils.getRowMetaForUpdate when a key stream field listed for a database update/lookup operation is not present in the incoming row metadata. It means the mapping between the table key columns (keyLookup) and the stream fields (keyStream) references a field name the input rows don't provide.

Solutions

  1. Open the Update/Insert-Update step and re-map the key fields to existing input fields (Get Fields)
  2. Trace upstream: find where the field was renamed or removed and fix the reference
  3. Use 'Get update fields'/'Get fields' button in the step dialog to refresh mappings after schema changes
  4. Add a Select Values step aliasing the new field name back to the expected name if renaming is intentional

Example fix

// before: keyStream references deleted field
keyStream = ["old_id"]; keyLookup = ["ID"]  // old_id no longer in rows
// after: remap to current field
keyStream = ["new_id"]; keyLookup = ["ID"]  // new_id exists in input rows
Defensive patterns

Strategy: validation

Validate before calling

// Validate key stream fields exist in previous step's row meta before running
RowMetaInterface prev = transMeta.getPrevStepFields(updateStepName);
for (int i = 0; i < keyStream.length; i++) {
  if (prev.searchValueMeta(keyStream[i]) == null) {
    throw new IllegalStateException("Field not in input rows: " + keyStream[i]);
  }
}

Try / catch

try {
  transMeta.prepareExecution(variables);
} catch (KettleStepException e) {
  if (e.getMessage().startsWith("Unable to find field [")) {
    String field = e.getMessage().replaceAll(".*\\[(.*)\\].*", "$1");
    log.error("Remap key field in Update step: " + field);
  }
  throw e;
}

Prevention

When it happens

Trigger: getRowMetaForUpdate called during metadata initialization of insert/update/delete steps; prev.searchValueMeta(keyStream[i]) returns null because keyStream[i] names a field absent from the previous step's output rows — typically after renaming/deleting fields upstream.

Common situations: Renaming a field in an upstream Select values step without updating the Update/Insert-Update step's key mapping; a source column dropped in a table input step; copied transformation with field references stale after schema change.

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/e2e7117c3f416095. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/utils/RowMetaUtils.java:38

import org.pentaho.di.core.row.ValueMetaInterface;

public class RowMetaUtils {

  public static RowMetaInterface getRowMetaForUpdate( RowMetaInterface prev, String[] keyLookup, String[] keyStream,
      String[] updateLookup, String[] updateStream ) throws KettleStepException {
    RowMetaInterface tableFields = new RowMeta();

    // Now change the field names
    // the key fields
    if ( keyLookup != null ) {
      for ( int i = 0; i < keyLookup.length; i++ ) {
        ValueMetaInterface v = prev.searchValueMeta( keyStream[i] );
        if ( v != null ) {
          ValueMetaInterface tableField = v.clone();
          tableField.setName( keyLookup[i] );
          tableFields.addValueMeta( tableField );
        } else {
          throw new KettleStepException( "Unable to find field [" + keyStream[i] + "] in the input rows" );
        }
      }
    }
    // the lookup fields
    for ( int i = 0; i < updateLookup.length; i++ ) {
      ValueMetaInterface v = prev.searchValueMeta( updateStream[i] );
      if ( v != null ) {
        ValueMetaInterface vk = tableFields.searchValueMeta( updateLookup[i] );
        if ( vk == null ) { // do not add again when already added as key fields
          ValueMetaInterface tableField = v.clone();
          tableField.setName( updateLookup[i] );
          tableFields.addValueMeta( tableField );
        }
      } else {
        throw new KettleStepException( "Unable to find field [" + updateStream[i] + "] in the input rows" );
      }
    }
    return tableFields;

View on GitHub (pinned to f3058517a1)