{"record":{"id":"834957453744f4a6","repo":"pentaho/pentaho-kettle","slug":"error-loading-transformation-step-from-xml","errorCode":null,"errorMessage":"Error loading transformation step from XML","messagePattern":"Error loading transformation step from XML","errorType":"exception","errorClass":"KettleXMLException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java","lineNumber":162,"sourceCode":"        inputMapping = new MappingIODefinition( mappingNode );\n      } else {\n        inputMapping = new MappingIODefinition(); // empty\n      }\n      Node outputNode = XMLHandler.getSubNode( mappingsNode, \"output\" );\n      mappingNode = XMLHandler.getSubNode( outputNode, MappingIODefinition.XML_TAG );\n      if ( mappingNode != null ) {\n        outputMapping = new MappingIODefinition( mappingNode );\n      } else {\n        outputMapping = new MappingIODefinition(); // empty\n      }\n\n      // Load the mapping parameters too..\n      //\n      Node mappingParametersNode = XMLHandler.getSubNode( mappingsNode, MappingParameters.XML_TAG );\n      mappingParameters = new MappingParameters( mappingParametersNode );\n\n    } catch ( Exception e ) {\n      throw new KettleXMLException( BaseMessages.getString(\n        PKG, \"SimpleMappingMeta.Exception.ErrorLoadingTransformationStepFromXML\" ), e );\n    }\n  }\n\n  public Object clone() {\n    Object retval = super.clone();\n    return retval;\n  }\n\n  public String getXML() {\n    StringBuilder retval = new StringBuilder( 300 );\n\n    retval.append( \"    \" ).append(\n      XMLHandler.addTagValue( \"specification_method\", specificationMethod == null ? null : specificationMethod\n        .getCode() ) );\n    retval.append( \"    \" ).append(\n      XMLHandler.addTagValue( \"trans_object_id\", transObjectId == null ? null : transObjectId.toString() ) );\n    // Export a little bit of extra information regarding the reference since it doesn't really matter outside the same","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java#L144-L180","documentation":"SimpleMappingMeta.loadXML wraps the whole XML deserialization of the step in a try/catch; any exception while reading mappings, input/output MappingIODefinition entries, or MappingParameters is rethrown as a KettleXMLException with the message 'Error loading transformation step from XML' and the original cause attached.","triggerScenarios":"Any Exception thrown inside loadXML while parsing the <mappings> node, its <input>/<output> children (MappingIODefinition.XML_TAG) or the <mapping_parameters> (MappingParameters.XML_TAG) node - typically malformed or unexpected XML structure.","commonSituations":"Truncated .ktr files (incomplete save or disk issue); XML edited by hand with wrong tag names or nesting; version skew where an older engine reads XML written by a newer version with extra/renamed elements; corrupted content pulled from a repository.","solutions":["Look at the chained cause (e.getCause()) in the stack trace to find the exact parse failure.","Open the .ktr in an XML editor/linter and validate well-formedness and the expected <mappings> structure.","Restore the step or file from a previous saved version / repository history.","Rebuild the Simple Mapping step in Spoon and save a fresh copy of the transformation.","Align Pentaho Data Integration versions between the writer and reader of the file."],"exampleFix":"// Malformed parameter block\n<mapping_parameters><parameter><name>p1</name></mapping_parameters>\n// after - properly closed\n<mapping_parameters><parameter><name>p1</name><value>1</value></parameter></mapping_parameters>","handlingStrategy":"try-catch","validationCode":"// Validate XML well-formedness and required nodes before loading\nDocument doc = XMLHandler.loadXMLFile(file);\nif (doc == null) throw new IllegalStateException(\"XML is not well-formed: \" + file);","typeGuard":null,"tryCatchPattern":"try {\n  transMeta.loadXML(fileName, null, metaStore, variables, false, null);\n} catch (KettleXMLException e) {\n  Throwable root = e; while (root.getCause() != null) root = root.getCause();\n  logError(\"Error loading step XML, root cause: \" + root.getMessage(), e);\n}","preventionTips":["Always inspect the chained cause - the top-level message is generic","Save transformations through Spoon to guarantee complete, well-formed XML","Keep Pentaho Data Integration read/write versions aligned across environments"],"tags":["kettle","pdi","xml","serialization","parse-error"],"backgroundTag":"json-parse-error","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}