pentaho/pentaho-kettle · error · KettleXMLException

MappingMeta.Exception.ErrorLoadingTransformationStepFromXML

MappingMeta.Exception.ErrorLoadingTransformationStepFromXML

Error message

Error loading transformation step from XML

What it means

A KettleXMLException wrapper thrown by MappingMeta.loadXML when any exception occurs while parsing the Mapping step's XML node (input/output mappings, allow_multi_input/output tags, etc.). It indicates the persisted step metadata is malformed or unreadable.

Solutions

  1. Inspect the wrapped cause (e.getCause()) to find the exact parse failure
  2. Open the .ktr in a text editor and validate/fix the Mapping step's XML tags
  3. Re-create the Mapping step in the UI and re-save the transformation
  4. Align PDI versions between the authoring and reading environments

Example fix

// hand-edited XML before
<allow_multi_input>yes</allow_multi_input>
// after (valid boolean format expected by XMLHandler)
<allow_multi_input>Y</allow_multi_input>
Defensive patterns

Strategy: try-catch

Validate before calling

// validate the step XML before loadXML
String xml = XMLHandler.getNodeXML(stepnode);
if (xml == null || !xml.contains("<input_mapping>")) {
  logError("Mapping step XML looks malformed");
}

Type guard

boolean isParsableNode(Node node) { return node != null && node.getNodeType() == Node.ELEMENT_NODE; }

Try / catch

try {
  meta.loadXML(stepnode, databases, metaStore, lsp);
} catch (KettleXMLException e) {
  logError("Failed to load mapping step from XML: " + e.getCause(), e);
  // re-create the step or restore the .ktr from version control
}

Prevention

When it happens

Trigger: loadXML(stepnode...) throws inside its try block — e.g. unexpected child tags, corrupt XML, incompatible step metadata produced by a different Pentaho version.

Common situations: Opening a transformation saved by a newer/older PDI version; hand-edited or truncated .ktr XML; merge conflicts in the XML file; repository metadata corruption.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java:216

        inputMappings.add( inputMappingDefinition );
        outputMappings.add( outputMappingDefinition );

        // The default is to have no mapping parameters: the concept didn't
        // exist before.
        //
        mappingParameters = new MappingParameters();

      }

      String multiInput = XMLHandler.getTagValue( stepnode, "allow_multiple_input" );
      allowingMultipleInputs =
        Utils.isEmpty( multiInput ) ? inputMappings.size() > 1 : "Y".equalsIgnoreCase( multiInput );
      String multiOutput = XMLHandler.getTagValue( stepnode, "allow_multiple_output" );
      allowingMultipleOutputs =
        Utils.isEmpty( multiOutput ) ? outputMappings.size() > 1 : "Y".equalsIgnoreCase( multiOutput );

    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "MappingMeta.Exception.ErrorLoadingTransformationStepFromXML" ), e );
    }
  }

  public Object clone() {
    Object retval = super.clone();
    return retval;
  }

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

    retval.append( "    " ).append(
      XMLHandler.addTagValue( "specification_method", specificationMethod == null ? null : specificationMethod
        .getCode() ) );
    retval.append( "    " ).append(
      XMLHandler.addTagValue( "trans_object_id", transObjectId == null ? null : transObjectId.toString() ) );
    // Export a little bit of extra information regarding the reference since it doesn't really matter outside the same

View on GitHub (pinned to f3058517a1)