pentaho/pentaho-kettle · error · KettleStepException

FlattenerMeta.Exception.UnableToLocateFieldInInputFields

FlattenerMeta.Exception.UnableToLocateFieldInInputFields

Error message

FlattenerMeta.Exception.UnableToLocateFieldInInputFields

What it means

FlattenerMeta.getFields validates row layout at transformation initialization and throws KettleStepException with this localized message when the configured 'field to flatten' (fieldName) is not present in the incoming row's fields. The flattener needs that key column to group rows.

Solutions

  1. Open the Flattener step and re-select 'The field to flatten' from the actual incoming fields
  2. Verify the upstream step still emits that field (preview the input stream)
  3. Fix field-name casing/typos — matching is exact
  4. Re-run getFields/preview to confirm the row layout now contains the field

Example fix

// before
String fieldName = "cust_name"; // upstream renamed it
// after
String fieldName = "customer_name"; // match the actual upstream field
Defensive patterns

Strategy: validation

Validate before calling

// before running: verify the flatten field exists in the incoming stream
String[] fields = transMeta.getPrevStepFields( stepMeta ).getFieldNames();
boolean found = java.util.Arrays.asList( fields ).contains( "fieldToFlatten" );
if ( !found ) throw new IllegalStateException( "Field 'fieldToFlatten' not in input stream" );

Try / catch

try {
  trans.execute( null );
} catch ( KettleStepException e ) {
  if ( String.valueOf( e.getMessage() ).contains( "UnableToLocateFieldInInputFields" ) ||
       String.valueOf( e.getMessage() ).contains( "field to flatten" ) ) {
    // re-check upstream field names and step config
  }
}

Prevention

When it happens

Trigger: Running/previewing a Flattener step whose fieldName does not match any value name in the incoming RowMeta — indexOfValue returns -1.

Common situations: Renamed or removed the source field upstream; connected the wrong stream into the Flattener; typo or case mismatch in the field name after editing the transformation.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/flattener/FlattenerMeta.java:108

    return retval;
  }

  public void setDefault() {
    int nrfields = 0;

    allocate( nrfields );
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface row, String name, RowMetaInterface[] info, StepMeta nextStep,
    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {

    // Remove the key value (there will be different entries for each output row)
    //
    if ( fieldName != null && fieldName.length() > 0 ) {
      int idx = row.indexOfValue( fieldName );
      if ( idx < 0 ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "FlattenerMeta.Exception.UnableToLocateFieldInInputFields", fieldName ) );
      }

      ValueMetaInterface v = row.getValueMeta( idx );
      row.removeValueMeta( idx );

      for ( int i = 0; i < targetField.length; i++ ) {
        ValueMetaInterface value = v.clone();
        value.setName( targetField[i] );
        value.setOrigin( name );

        row.addValueMeta( value );
      }
    } else {
      throw new KettleStepException( BaseMessages.getString( PKG, "FlattenerMeta.Exception.FlattenFieldRequired" ) );
    }
  }

View on GitHub (pinned to f3058517a1)