pentaho/pentaho-kettle · error · KettleXMLException

UpdateMeta.Exception.UnableToReadStepInfoFromXML

Error message

UpdateMeta.Exception.UnableToReadStepInfoFromXML

What it means

UpdateMeta.readData failed while parsing the step's XML definition with XMLHandler; any Exception is wrapped in a KettleXMLException with the UnableToReadStepInfoFromXML message. This happens when loading a transformation (.ktr) that contains an Update step.

Solutions

  1. Open the .ktr in Spoon to see if it loads and repair the Update step's XML section
  2. Validate the <update> block structure (lookup, key, value, rename tags) against a working example
  3. Compare file against a version-control copy to find the corrupt/removed tag
  4. Upgrade/downgrade PDI to match the version that authored the file

Example fix

// before (malformed XML)
<rename></stream>
// after
<rename>customer_name</rename>
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate .ktr XML before load:
// Document d = XMLHandler.loadXMLFile(ktrFile); // check <update> step block parses and tags exist

Try / catch

try { transMeta.loadXML(file, ...); } catch (KettleXMLException e) { log.error("Failed to parse Update step XML: " + e.getMessage(), e); }

Prevention

When it happens

Trigger: loadXML -> readData throws while reading <lookup>/<update> tags; malformed or hand-edited XML, missing tags, or unexpected element structure.

Common situations: Manually edited or corrupted .ktr files; XML produced by a different PDI version with a changed schema; truncation of file contents.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/update/UpdateMeta.java:411

        keyLookup[i] = XMLHandler.getTagValue( knode, "field" );
        keyCondition[i] = XMLHandler.getTagValue( knode, "condition" );
        if ( keyCondition[i] == null ) {
          keyCondition[i] = "=";
        }
        keyStream2[i] = XMLHandler.getTagValue( knode, "name2" );
      }

      for ( int i = 0; i < nrvalues; i++ ) {
        Node vnode = XMLHandler.getSubNodeByNr( lookup, "value", i );

        updateLookup[i] = XMLHandler.getTagValue( vnode, "name" );
        updateStream[i] = XMLHandler.getTagValue( vnode, "rename" );
        if ( updateStream[i] == null ) {
          updateStream[i] = updateLookup[i]; // default: the same name!
        }
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "UpdateMeta.Exception.UnableToReadStepInfoFromXML" ), e );
    }
  }

  @Override
  public void setDefault() {
    skipLookup = false;
    keyStream = null;
    updateLookup = null;
    databaseMeta = null;
    commitSize = "100";
    schemaName = "";
    tableName = BaseMessages.getString( PKG, "UpdateMeta.DefaultTableName" );

    int nrkeys = 0;
    int nrvalues = 0;

    allocate( nrkeys, nrvalues );

View on GitHub (pinned to f3058517a1)