{"record":{"id":"0eaea48cc5f36c66","repo":"pentaho/pentaho-kettle","slug":"mappingmeta-exception-errorloadingtransformationstepfromxml","errorCode":"MappingMeta.Exception.ErrorLoadingTransformationStepFromXML","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/mapping/MappingMeta.java","lineNumber":216,"sourceCode":"        inputMappings.add( inputMappingDefinition );\n        outputMappings.add( outputMappingDefinition );\n\n        // The default is to have no mapping parameters: the concept didn't\n        // exist before.\n        //\n        mappingParameters = new MappingParameters();\n\n      }\n\n      String multiInput = XMLHandler.getTagValue( stepnode, \"allow_multiple_input\" );\n      allowingMultipleInputs =\n        Utils.isEmpty( multiInput ) ? inputMappings.size() > 1 : \"Y\".equalsIgnoreCase( multiInput );\n      String multiOutput = XMLHandler.getTagValue( stepnode, \"allow_multiple_output\" );\n      allowingMultipleOutputs =\n        Utils.isEmpty( multiOutput ) ? outputMappings.size() > 1 : \"Y\".equalsIgnoreCase( multiOutput );\n\n    } catch ( Exception e ) {\n      throw new KettleXMLException( BaseMessages.getString(\n        PKG, \"MappingMeta.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":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java#L198-L234","documentation":"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.","triggerScenarios":"loadXML(stepnode...) throws inside its try block — e.g. unexpected child tags, corrupt XML, incompatible step metadata produced by a different Pentaho version.","commonSituations":"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.","solutions":["Inspect the wrapped cause (e.getCause()) to find the exact parse failure","Open the .ktr in a text editor and validate/fix the Mapping step's XML tags","Re-create the Mapping step in the UI and re-save the transformation","Align PDI versions between the authoring and reading environments"],"exampleFix":"// hand-edited XML before\n<allow_multi_input>yes</allow_multi_input>\n// after (valid boolean format expected by XMLHandler)\n<allow_multi_input>Y</allow_multi_input>","handlingStrategy":"try-catch","validationCode":"// validate the step XML before loadXML\nString xml = XMLHandler.getNodeXML(stepnode);\nif (xml == null || !xml.contains(\"<input_mapping>\")) {\n  logError(\"Mapping step XML looks malformed\");\n}","typeGuard":"boolean isParsableNode(Node node) { return node != null && node.getNodeType() == Node.ELEMENT_NODE; }","tryCatchPattern":"try {\n  meta.loadXML(stepnode, databases, metaStore, lsp);\n} catch (KettleXMLException e) {\n  logError(\"Failed to load mapping step from XML: \" + e.getCause(), e);\n  // re-create the step or restore the .ktr from version control\n}","preventionTips":["Don't hand-edit .ktr XML; use Spoon","Keep PDI versions consistent across environments","Commit transformations to version control so corrupt XML can be reverted"],"tags":["kettle","xml","deserialization","metadata"],"backgroundTag":"xml-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"}