pentaho/pentaho-kettle · error · KettleXMLException

InsertUpdateMeta.Exception.UnableToReadStepInfoFromXML

Error message

InsertUpdateMeta.Exception.UnableToReadStepInfoFromXML

What it means

loadXML could not parse the Insert/Update step's XML definition; any exception while reading the key/update field configuration in readData is wrapped in a KettleXMLException. The .ktr file's XML for this step is malformed or contains unexpected content.

Solutions

Open the .ktr in a text editor, locate the <step> block for this Insert/Update step, and fix malformed XML or field elements.
Restore the transformation from version control or backup.
Open the file in the matching (or newer) PDI version that wrote it.
Check the wrapped cause exception in the log to pinpoint the failing element/attribute.

Example fix

<!-- before: broken field element -->
<field><name>id</name><update>m aybe</update></field>
<!-- after -->
<field><name>id</name><update>Y</update></field>

Defensive patterns

Strategy: try-catch

Validate before calling

// validate .ktr XML before loading
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.newDocumentBuilder().parse(new File("trans.ktr")); // throws if malformed

Type guard

null

Try / catch

try { transMeta = new TransMeta("trans.ktr", metaStore); }
catch (KettleXMLException e) {
  logError("Step XML unreadable; cause:", e.getCause()); // inspect which element failed
  throw e;
}

Prevention

Avoid hand-editing .ktr files; use Spoon for metadata changes.
Resolve git merge conflicts in .ktr files carefully and re-open in Spoon to verify.
Open files with the same or newer PDI version that produced them.
Keep backups of transformations before bulk edits.

When it happens

Trigger: Hand-edited .ktr with broken XML or wrong element structure; git merge conflict resolved incorrectly; older PDI version reading attributes written by a newer version; attribute values (e.g. non-boolean 'update' flag) that throw during parsing.

Common situations: Merging transformation XML by hand across branches; corrupted/truncated file transfer; opening a newer-version .ktr in an older PDI.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdateMeta.java:283

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

  public void setDefault() {
    databaseMeta = null;
    commitSize = "100";
    schemaName = "";
    tableName = BaseMessages.getString( PKG, "InsertUpdateMeta.DefaultTableName" );

    int nrkeys = 0;
    int nrvalues = 0;

    allocate( nrkeys, nrvalues );

    for ( int i = 0; i < nrkeys; i++ ) {
      keyFields[ i ].setKeyLookup( "age" );
      keyFields[ i ].setKeyCondition( "BETWEEN" );

View on GitHub (pinned to f3058517a1)