pentaho/pentaho-kettle · error · KettleXMLException

FlattenerMeta.Exception.UnableToLoadStepInfoFromXML

FlattenerMeta.Exception.UnableToLoadStepInfoFromXML

Error message

FlattenerMeta.Exception.UnableToLoadStepInfoFromXML

What it means

FlattenerMeta.readData (called by loadXML) wraps any exception while parsing the Flattener step's XML (<field_name> and the <fields>/<field>/<name> entries) in a KettleXMLException with this localized message, chaining the parse error.

Solutions

  1. Validate the Flattener step's XML block in the .ktr (field_name plus fields/field/name nodes)
  2. Check the chained cause for the exact failing tag
  3. Recreate the step in Spoon and re-save to regenerate valid XML
  4. Normalize PDI versions between file producer and consumer

Example fix

// before
Node fnode = XMLHandler.getSubNodeByNr( fields, "field", i ); // null-safe gap -> NPE on getTagValue
// after
Node fnode = XMLHandler.getSubNodeByNr( fields, "field", i );
if ( fnode == null ) { continue; }
targetField[i] = XMLHandler.getTagValue( fnode, "name" );
Defensive patterns

Strategy: try-catch

Validate before calling

// validate Flattener XML before load
if ( XMLHandler.getTagValue( stepnode, "field_name" ) == null ) {
  throw new IllegalArgumentException( "Flattener XML missing field_name tag" );
}

Try / catch

try {
  transMeta = new TransMeta( inputStream, provider, true, variables, listener );
} catch ( KettleXMLException e ) {
  logError( "Flattener XML load failed: " + e.getCause(), e );
}

Prevention

When it happens

Trigger: loadXML on a FlattenerMeta when the step node is missing expected tags, or a <field> subnode is malformed, causing XMLHandler calls or the array fill to fail.

Common situations: Hand-edited .ktr files; truncated transformation XML; version drift where the step XML layout differs between PDI releases; clipboard corruption when pasting steps.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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

Appendix: source

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

      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(
        PKG, "FlattenerMeta.Exception.UnableToLoadStepInfoFromXML" ), e );
    }
  }

  public String getXML() {
    StringBuilder retval = new StringBuilder();

    retval.append( "      " + XMLHandler.addTagValue( "field_name", fieldName ) );

    retval.append( "      <fields>" + Const.CR );
    for ( int i = 0; i < targetField.length; i++ ) {
      retval.append( "        <field>" + Const.CR );
      retval.append( "          " + XMLHandler.addTagValue( "name", targetField[i] ) );
      retval.append( "          </field>" + Const.CR );
    }
    retval.append( "        </fields>" + Const.CR );

    return retval.toString();

View on GitHub (pinned to f3058517a1)