{"record":{"id":"46f7d2ce41f5360c","repo":"pentaho/pentaho-kettle","slug":"error0001-databaselookupmeta-unabletoloadstepfromxml","errorCode":"ERROR0001","errorMessage":"DatabaseLookupMeta.ERROR0001.UnableToLoadStepFromXML","messagePattern":"DatabaseLookupMeta\\.ERROR0001\\.UnableToLoadStepFromXML","errorType":"exception","errorClass":"KettleXMLException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookupMeta.java","lineNumber":468,"sourceCode":"      for ( int i = 0; i < nrValues; i++ ) {\n        Node vnode = XMLHandler.getSubNodeByNr( lookup, TAG_VALUE, i );\n\n        returnValueField[ i ] = XMLHandler.getTagValue( vnode, TAG_NAME );\n        returnValueNewName[ i ] = XMLHandler.getTagValue( vnode, TAG_RENAME );\n        if ( returnValueNewName[ i ] == null ) {\n          returnValueNewName[ i ] = returnValueField[ i ]; // default: the same name!\n        }\n        returnValueDefault[ i ] = XMLHandler.getTagValue( vnode, TAG_DEFAULT );\n        returnValueDefaultType[ i ] = ValueMetaFactory.getIdForValueMeta( XMLHandler.getTagValue( vnode, TAG_TYPE ) );\n        if ( returnValueDefaultType[ i ] < 0 ) {\n          returnValueDefaultType[ i ] = ValueMetaInterface.TYPE_STRING;\n        }\n      }\n      orderByClause = XMLHandler.getTagValue( lookup, TAG_ORDERBY ); // Optional, can by null\n      failingOnMultipleResults = \"Y\".equalsIgnoreCase( XMLHandler.getTagValue( lookup, TAG_FAIL_ON_MULTIPLE ) );\n      eatingRowOnLookupFailure = \"Y\".equalsIgnoreCase( XMLHandler.getTagValue( lookup, TAG_EAT_ROW_ON_FAILURE ) );\n    } catch ( Exception e ) {\n      throw new KettleXMLException( BaseMessages.getString(\n        PKG, \"DatabaseLookupMeta.ERROR0001.UnableToLoadStepFromXML\" ), e );\n    }\n  }\n\n  @Override\n  public void setDefault() {\n    streamKeyField1 = null;\n    returnValueField = null;\n    databaseMeta = null;\n    cached = false;\n    cacheSize = 0;\n    schemaName = \"\";\n    tablename = BaseMessages.getString( PKG, \"DatabaseLookupMeta.Default.TableName\" );\n\n    allocate( 0, 0 );\n\n    orderByClause = \"\";\n    failingOnMultipleResults = false;","sourceCodeStart":450,"sourceCodeEnd":486,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookupMeta.java#L450-L486","documentation":"DatabaseLookupMeta.readData() wraps any exception raised while parsing the step's XML definition (Node tree produced by getXML) into a KettleXMLException 'Unable to load step from XML'. Thrown during transformation deserialization from .ktr files when XMLHandler tag reads or value-type conversion fail.","triggerScenarios":"loadXML() parses a transformation whose DatabaseLookup step XML is malformed, missing required child tags (lookup/condition elements), or contains an invalid value-type string in TAG_RETURN_VALUE_TYPE.","commonSituations":"Hand-edited or truncated .ktr file; XML saved by a newer Kettle version with tags an older parser mishandles; copy-pasting a step XML between transformations dropped required sub-nodes.","solutions":["Open the .ktr in a text editor and check the <database_lookup> step XML is well-formed and complete","Recreate the Database Lookup step in Spoon and re-save the transformation","Check the nested cause for the exact tag/conversion that failed","Align Kettle versions between the tool that saved and the tool that loads the file"],"exampleFix":"// before (broken ktr fragment)\n<return_value_type>NUMBR</return_value_type>\n// after\n<return_value_type>Number</return_value_type> <!-- valid ValueMeta type name -->","handlingStrategy":"try-catch","validationCode":"// validate the ktr parses before loading\ntry {\n  Document doc = XMLHandler.loadXMLFile( ktrFile );\n  if ( XMLHandler.getSubNode( doc, \"transformation\" ) == null ) throw new KettleXMLException( \"Not a transformation\" );\n} catch ( Exception e ) { /* file malformed */ }","typeGuard":null,"tryCatchPattern":"try {\n  transMeta = new TransMeta( ktrFile );\n} catch ( KettleXMLException e ) {\n  if ( e.getMessage() != null && e.getMessage().contains( \"Unable to load step info from XML\" ) ) {\n    logError( \"Corrupt DatabaseLookup step XML; cause=\" + e.getCause(), e );\n  } else { throw e; }\n}","preventionTips":["Never hand-edit .ktr XML without validating afterwards","Keep Kettle versions consistent between writers and readers of .ktr files","Back up transformations before editing XML directly","Recreate corrupted steps in Spoon rather than patching XML by hand"],"tags":["kettle","xml","deserialization"],"backgroundTag":"json-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"}