pentaho/pentaho-kettle · error · KettleStepException

FlattenerMeta.Exception.FlattenFieldRequired

FlattenerMeta.Exception.FlattenFieldRequired

Error message

FlattenerMeta.Exception.FlattenFieldRequired

What it means

FlattenerMeta.getFields throws KettleStepException with this localized message when no target fields are configured for the flattener (targetField is empty/null), so the step would produce no output columns. It is a configuration-completeness check.

Solutions

  1. Open the Flattener dialog and add at least one target field name
  2. Verify the saved XML/repository entry contains the <fields><field><name> entries
  3. When building metadata in code, call allocate(n) and populate targetField before execution
  4. Re-save the transformation after configuring to persist the field list

Example fix

// before
flattenerMeta.allocate( 0 ); // no targets -> FlattenFieldRequired
// after
flattenerMeta.allocate( 1 );
flattenerMeta.setTargetField( new String[] { "flattened_value" } );
Defensive patterns

Strategy: validation

Validate before calling

// before running: ensure at least one target field is configured
String[] targets = flattenerMeta.getTargetField();
if ( targets == null || targets.length == 0 ) {
  throw new IllegalStateException( "Flattener step has no target fields configured" );
}

Try / catch

try {
  trans.execute( null );
} catch ( KettleStepException e ) {
  if ( String.valueOf( e.getMessage() ).contains( "FlattenFieldRequired" ) ||
       String.valueOf( e.getMessage() ).contains( "flatten field" ) ) {
    // open the step dialog and add target fields
  }
}

Prevention

When it happens

Trigger: Executing a Flattener step where loadXML/readRep produced an empty targetField array — e.g., the step was never configured, or its <fields> list was lost.

Common situations: Step copied from a broken transformation; fields list cleared accidentally in the dialog; repository/XML load that silently dropped the target fields; building the transformation programmatically without setting target fields.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    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" ) );
    }
  }

  private void readData( Node stepnode ) throws KettleXMLException {
    try {
      fieldName = XMLHandler.getTagValue( stepnode, "field_name" );

      Node fields = XMLHandler.getSubNode( stepnode, "fields" );
      int nrfields = XMLHandler.countNodes( fields, "field" );

      allocate( nrfields );

      for ( int i = 0; i < nrfields; i++ ) {
        Node fnode = XMLHandler.getSubNodeByNr( fields, "field", i );
        targetField[i] = XMLHandler.getTagValue( fnode, "name" );
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(

View on GitHub (pinned to f3058517a1)