{"record":{"id":"c123ddfcd9548262","repo":"pentaho/pentaho-kettle","slug":"unable-to-find-mappings-element-in-the-step-xml","errorCode":null,"errorMessage":"Unable to find <mappings> element in the step XML","messagePattern":"Unable to find <mappings> element in the step XML","errorType":"exception","errorClass":"KettleXMLException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java","lineNumber":136,"sourceCode":"  public void loadXML( Node stepnode, List<DatabaseMeta> databases, IMetaStore metaStore ) throws KettleXMLException {\n    try {\n      String method = XMLHandler.getTagValue( stepnode, \"specification_method\" );\n      specificationMethod = ObjectLocationSpecificationMethod.getSpecificationMethodByCode( method );\n      String transId = XMLHandler.getTagValue( stepnode, \"trans_object_id\" );\n      transObjectId = Utils.isEmpty( transId ) ? null : new StringObjectId( transId );\n\n      transName = XMLHandler.getTagValue( stepnode, \"trans_name\" );\n      fileName = XMLHandler.getTagValue( stepnode, \"filename\" );\n      directoryPath = XMLHandler.getTagValue( stepnode, \"directory_path\" );\n\n      // Backward compatibility check for object specification\n      //\n      checkObjectLocationSpecificationMethod();\n\n      Node mappingsNode = XMLHandler.getSubNode( stepnode, \"mappings\" );\n\n      if ( mappingsNode == null ) {\n        throw new KettleXMLException( \"Unable to find <mappings> element in the step XML\" );\n      }\n\n      // Read all the input mapping definitions...\n      //\n      Node inputNode = XMLHandler.getSubNode( mappingsNode, \"input\" );\n      Node mappingNode = XMLHandler.getSubNode( inputNode, MappingIODefinition.XML_TAG );\n      if ( mappingNode != null ) {\n        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      }","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java#L118-L154","documentation":"When deserializing a Simple Mapping step from a .ktr XML file, SimpleMappingMeta.loadXML looks for the mandatory <mappings> wrapper element that holds the input/output mapping definitions and parameters. If XMLHandler.getSubNode(stepnode, \"mappings\") returns null, the step XML is malformed or from an unexpected format, so a KettleXMLException is thrown.","triggerScenarios":"loadXML() parses a step node whose XML contains no <mappings> child - e.g. a hand-edited or truncated .ktr file, XML produced by an incompatible/older plugin version, or a corrupted repository export.","commonSituations":"Hand-editing a .ktr and deleting/renaming the <mappings> element; merging XML in git and dropping the block; loading a transformation produced by a different Pentaho/Data Integration version with a changed step serialization; copying a step's XML snippet from another step type.","solutions":["Inspect the .ktr XML and ensure the Simple Mapping step node contains a <mappings> element with <input>, <output> and <parameters> children; restore it from a backup.","Re-create the Simple Mapping step in Spoon and reconfigure it, then save - this regenerates correct XML.","Use version control history (git show / repository history) to recover the last valid version of the file.","Verify you are opening the file with a compatible Pentaho Data Integration version (serialization format mismatch)."],"exampleFix":"// before (broken step XML)\n<step><name>Mapping</name><type>SimpleMapping</type></step>\n// after\n<step><name>Mapping</name><type>SimpleMapping</type>\n  <mappings>\n    <input>...</input>\n    <output>...</output>\n    <parameters>...</parameters>\n  </mappings>\n</step>","handlingStrategy":"try-catch","validationCode":"// Pre-validate .ktr XML before loading\nDocument doc = XMLHandler.loadXMLFile(transformationFile);\nNode stepsNode = XMLHandler.getSubNode(doc, \"transformation\", \"steps\");\nfor (int i = 0; i < XMLHandler.countNodes(stepsNode, \"step\"); i++) {\n  Node s = XMLHandler.getSubNodeByNr(stepsNode, \"step\", i);\n  if (\"SimpleMapping\".equals(XMLHandler.getTagValue(s, \"type\"))\n      && XMLHandler.getSubNode(s, \"mappings\") == null) {\n    throw new IllegalStateException(\"SimpleMapping step XML missing <mappings> element\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  meta.loadXML(stepnode, databases, metaStore, variables);\n} catch (KettleXMLException e) {\n  logError(\"Corrupt SimpleMapping step XML (missing <mappings>): \" + e.getMessage());\n  throw new IllegalStateException(\"Restore the .ktr from backup\", e);\n}","preventionTips":["Never hand-edit .ktr XML; edit steps through Spoon","Keep .ktr files in version control so corrupt edits can be reverted","Run an XML schema/well-formedness check in CI on transformation files"],"tags":["kettle","pdi","xml","serialization","corrupt-file"],"backgroundTag":"schema-validation-failed","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"}