{"record":{"id":"24fdf13f7cbeeec4","repo":"pentaho/pentaho-kettle","slug":"fuzzymatchmeta-exception-unabletoloadstepinfofromxml","errorCode":null,"errorMessage":"FuzzyMatchMeta.Exception.UnableToLoadStepInfoFromXML","messagePattern":"FuzzyMatchMeta\\.Exception\\.UnableToLoadStepInfoFromXML","errorType":"exception","errorClass":"KettleXMLException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatchMeta.java","lineNumber":407,"sourceCode":"      algorithm = getAlgorithmTypeByCode( Const.NVL( XMLHandler.getTagValue( stepnode, \"algorithm\" ), \"\" ) );\n\n      Node lookup = XMLHandler.getSubNode( stepnode, \"lookup\" );\n      int nrvalues = XMLHandler.countNodes( lookup, \"value\" );\n\n      allocate( nrvalues );\n\n      for ( int i = 0; i < nrvalues; i++ ) {\n        Node vnode = XMLHandler.getSubNodeByNr( lookup, \"value\", i );\n\n        value[i] = XMLHandler.getTagValue( vnode, \"name\" );\n        valueName[i] = XMLHandler.getTagValue( vnode, \"rename\" );\n        if ( valueName[i] == null ) {\n          valueName[i] = value[i]; // default: same name to return!\n        }\n      }\n\n    } catch ( Exception e ) {\n      throw new KettleXMLException( BaseMessages.getString(\n        PKG, \"FuzzyMatchMeta.Exception.UnableToLoadStepInfoFromXML\" ), e );\n    }\n  }\n\n  private static String getAlgorithmTypeCode( int i ) {\n    if ( i < 0 || i >= algorithmCode.length ) {\n      return algorithmCode[0];\n    }\n    return algorithmCode[i];\n  }\n\n  public void setDefault() {\n    value = null;\n    valueName = null;\n    separator = DEFAULT_SEPARATOR;\n    closervalue = true;\n    minimalValue = \"0\";\n    maximalValue = \"1\";","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatchMeta.java#L389-L425","documentation":"loadXML() delegates parsing of the step's <field> XML configuration to readData(); when any exception occurs while reading FuzzyMatch metadata from the transformation XML it is re-thrown as a KettleXMLException with message 'FuzzyMatchMeta.Exception.UnableToLoadStepInfoFromXML'. It indicates the step's serialized definition in the .ktr file could not be parsed.","triggerScenarios":"Calling FuzzyMatchMeta.loadXML(...) on a corrupted or hand-edited .ktr XML: missing/invalid attributes for lookup fields, wrong element structure, or an exception thrown by the XML node traversal (e.g. NullPointer on missing nodes).","commonSituations":"Opening a transformation saved by a different Pentaho version whose step XML schema changed; manual edit of the .ktr that removed <lookup> or <value> child nodes; truncated XML from bad source control merge.","solutions":["Open the .ktr in Spoon and fix/replace the FuzzyMatch step configuration; re-enter lookup and return field settings","Validate the XML structure of the step node (fields have 'name', 'rename' attributes; lookup nodes exist)","Compare the failing .ktr with a working one and restore the missing step attributes","Check Pentaho/Data Integration version compatibility; re-save with the current version","As a last resort, delete the FuzzyMatch step and re-add it, reconnecting hops"],"exampleFix":"// before (broken XML)\n<fields>\n  <field/>\n</fields>\n// after\n<fields>\n  <field name=\"lname\" rename=\"lname_match\"/>\n</fields>","handlingStrategy":"try-catch","validationCode":"Document doc = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(new File(\"trans.ktr\"));\nNodeList steps = doc.getElementsByTagName(\"step\");\nfor (int i = 0; i < steps.getLength(); i++) {\n  if (\"FuzzyMatch\".equals(((Element) steps.item(i)).getElementsByTagName(\"type\").item(0).getTextContent())) {\n    if (((Element) steps.item(i)).getElementsByTagName(\"lookup\").getLength() == 0)\n      throw new IllegalStateException(\"FuzzyMatch step XML missing lookup fields; fix .ktr before loading\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  meta.loadXML(stepnode, databases, metaStore);\n} catch (KettleXMLException e) {\n  log.error(\"Failed to load FuzzyMatch step from XML: \" + e.getCause(), e);\n  meta = new FuzzyMatchMeta(); // fall back to defaults and reconfigure\n}","preventionTips":["Never hand-edit .ktr files; use Spoon for all step configuration changes","Keep transformation files in version control and avoid manual merges of step XML","Validate .ktr files after version upgrades before relying on them","Avoid editing transformations with different Pentaho versions simultaneously"],"tags":["xml","serialization","metadata","pentaho-kettle"],"backgroundTag":"xml-unmarshal-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"}