pentaho/pentaho-kettle · error · KettleXMLException

VALUEMAPPER0004

VALUEMAPPER0004

Error message

ValueMapperMeta.RuntimeError.UnableToReadXML.VALUEMAPPER0004

What it means

ValueMapperMeta.loadXML -> readData wraps XML parsing of the step's <fields> definitions in a try/catch and rethrows any Exception as a KettleXMLException with message VALUEMAPPER0004 ('Unable to read XML'). It indicates the step's serialized configuration in the .ktr file could not be parsed.

Solutions

  1. Open the .ktr in a text editor and check the ValueMapper step's <fields> XML block for malformed or truncated nodes.
  2. Restore the transformation from backup or version control.
  3. Re-create the ValueMapper step in Spoon and re-enter mappings.
  4. Check the wrapped cause 'e' in the stack trace for the exact parse error position.

Example fix

// before (malformed)
<fields><field><source_value>A<target_value>B</field></fields>
// after
<fields><field><source_value>A</source_value><target_value>B</target_value></field></fields>
Defensive patterns

Strategy: try-catch

Validate before calling

// Before loading, sanity-check XML well-formedness:
DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new File(ktrPath));

Try / catch

try {
  transMeta.loadXML(new FileInputStream(ktr), null, this);
} catch (KettleXMLException e) {
  logError("Corrupt step XML: " + e.getMessage(), e);
  // fall back to backup file
}

Prevention

When it happens

Trigger: loadXML calls readData(stepnode); XMLHandler.getTagValue/getSubNodeByNr throws (malformed XML structure, unexpected node types) while reading field/source_value/target_value nodes.

Common situations: Corrupt or hand-edited .ktr file; schema mismatch after a PDI version upgrade; truncated file transfer; XML entities that break parsing.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/valuemapper/ValueMapperMeta.java:146

  private void readData( Node stepnode ) throws KettleXMLException {
    try {
      fieldToUse = XMLHandler.getTagValue( stepnode, "field_to_use" );
      targetField = XMLHandler.getTagValue( stepnode, "target_field" );
      nonMatchDefault = XMLHandler.getTagValue( stepnode, "non_match_default" );

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

      allocate( count );

      for ( int i = 0; i < count; i++ ) {
        Node fnode = XMLHandler.getSubNodeByNr( fields, "field", i );

        sourceValue[i] = XMLHandler.getTagValue( fnode, "source_value" );
        targetValue[i] = XMLHandler.getTagValue( fnode, "target_value" );
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "ValueMapperMeta.RuntimeError.UnableToReadXML.VALUEMAPPER0004" ), e );
    }
  }

  @Override
  public void setDefault() {
    int count = 0;

    allocate( count );

    for ( int i = 0; i < count; i++ ) {
      sourceValue[i] = "field" + i;
      targetValue[i] = "";
    }
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface r, String name, RowMetaInterface[] info, StepMeta nextStep,

View on GitHub (pinned to f3058517a1)