pentaho/pentaho-kettle · error · KettleXMLException

SynchronizeAfterMergeMeta.Exception.UnableToReadStepInfoFrom…

Error message

SynchronizeAfterMergeMeta.Exception.UnableToReadStepInfoFromXML

What it means

SynchronizeAfterMergeMeta.readData() failed while parsing the step's XML definition (as loaded by loadXML) into step metadata. Any exception during XML attribute reading (missing nodes, malformed values, wrong element structure) is wrapped in KettleXMLException 'Unable to read step info from XML'.

Solutions

  1. Open the .ktr in the PDI version it was created with, or upgrade Spoon to a compatible version
  2. Inspect the .ktr XML around the SynchronizeAfterMerge <fields> element and repair/normalize it (compare with a working step's XML)
  3. Recreate the step in a fresh transformation and re-enter the settings
  4. Check the cause ('Caused by') in the stack trace to identify the exact parse failure

Example fix

// before (hand-edited ktr, missing value_update element)
<field><value_name>AMOUNT</value_name><value_rename>amount</value_rename></field>
// after
<field><update>true</update><value_name>AMOUNT</value_name><value_rename>amount</value_rename></field>
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate XML before loading
try { javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new File(ktrPath)); }
catch (org.xml.sax.SAXException e) { throw new IllegalStateException("Malformed ktr XML: " + ktrPath, e); }

Try / catch

try { transMeta = new TransMeta(ktrPath); }
catch (KettleXMLException e) { log.error("Cannot read step from XML (check PDI version / ktr integrity): " + e.getMessage(), e); throw new IllegalStateException("Transformation file incompatible or corrupt", e); }

Prevention

When it happens

Trigger: Loading a .ktr file whose <fields> section for this step is malformed or from an incompatible plugin version; a repository/XML import of a transformation saved by a different Pentaho version with changed XML schema.

Common situations: Hand-editing a .ktr file and breaking the XML; opening transformations built in much older/newer PDI versions; incomplete file transfer truncating the XML.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/synchronizeaftermerge/SynchronizeAfterMergeMeta.java:468

        updateLookup[i] = XMLHandler.getTagValue( vnode, "name" );
        updateStream[i] = XMLHandler.getTagValue( vnode, "rename" );
        if ( updateStream[i] == null ) {
          updateStream[i] = updateLookup[i]; // default: the same name!
        }
        String updateValue = XMLHandler.getTagValue( vnode, "update" );
        if ( updateValue == null ) {
          // default TRUE
          update[i] = Boolean.TRUE;
        } else {
          if ( updateValue.equalsIgnoreCase( "Y" ) ) {
            update[i] = Boolean.TRUE;
          } else {
            update[i] = Boolean.FALSE;
          }
        }
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "SynchronizeAfterMergeMeta.Exception.UnableToReadStepInfoFromXML" ), e );
    }
  }

  public void setDefault() {
    tablenameInField = false;
    tablenameField = null;
    keyStream = null;
    updateLookup = null;
    databaseMeta = null;
    commitSize = "100";
    schemaName = "";
    tableName = BaseMessages.getString( PKG, "SynchronizeAfterMergeMeta.DefaultTableName" );
    operationOrderField = null;
    OrderInsert = null;
    OrderUpdate = null;
    OrderDelete = null;
    performLookup = false;

View on GitHub (pinned to f3058517a1)