pentaho/pentaho-kettle · error · KettleXMLException

ERROR0001

ERROR0001

Error message

DatabaseLookupMeta.ERROR0001.UnableToLoadStepFromXML

What it means

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.

Solutions

1. Open the .ktr in a text editor and check the <database_lookup> step XML is well-formed and complete
2. Recreate the Database Lookup step in Spoon and re-save the transformation
3. Check the nested cause for the exact tag/conversion that failed
4. Align Kettle versions between the tool that saved and the tool that loads the file

Example fix

// before (broken ktr fragment)
<return_value_type>NUMBR</return_value_type>
// after
<return_value_type>Number</return_value_type> <!-- valid ValueMeta type name -->

// validate the ktr parses before loading
try {
  Document doc = XMLHandler.loadXMLFile( ktrFile );
  if ( XMLHandler.getSubNode( doc, "transformation" ) == null ) throw new KettleXMLException( "Not a transformation" );
} catch ( Exception e ) { /* file malformed */ }

try {
  transMeta = new TransMeta( ktrFile );
} catch ( KettleXMLException e ) {
  if ( e.getMessage() != null && e.getMessage().contains( "Unable to load step info from XML" ) ) {
    logError( "Corrupt DatabaseLookup step XML; cause=" + e.getCause(), e );
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• ColumnExistsMeta.Exception.UnableToReadStepInfo
• CreditCardValidatorMeta.Exception.UnableToReadStepInfo
• CubeOutputMeta.Exception.UnableToLoadStepInfo
• DelayMeta.Exception.UnableToReadStepInfo
• DynamicSQLRowMeta.Exception.UnableToLoadStepInfo

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/46f7d2ce41f5360c. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookupMeta.java:468

      for ( int i = 0; i < nrValues; i++ ) {
        Node vnode = XMLHandler.getSubNodeByNr( lookup, TAG_VALUE, i );

        returnValueField[ i ] = XMLHandler.getTagValue( vnode, TAG_NAME );
        returnValueNewName[ i ] = XMLHandler.getTagValue( vnode, TAG_RENAME );
        if ( returnValueNewName[ i ] == null ) {
          returnValueNewName[ i ] = returnValueField[ i ]; // default: the same name!
        }
        returnValueDefault[ i ] = XMLHandler.getTagValue( vnode, TAG_DEFAULT );
        returnValueDefaultType[ i ] = ValueMetaFactory.getIdForValueMeta( XMLHandler.getTagValue( vnode, TAG_TYPE ) );
        if ( returnValueDefaultType[ i ] < 0 ) {
          returnValueDefaultType[ i ] = ValueMetaInterface.TYPE_STRING;
        }
      }
      orderByClause = XMLHandler.getTagValue( lookup, TAG_ORDERBY ); // Optional, can by null
      failingOnMultipleResults = "Y".equalsIgnoreCase( XMLHandler.getTagValue( lookup, TAG_FAIL_ON_MULTIPLE ) );
      eatingRowOnLookupFailure = "Y".equalsIgnoreCase( XMLHandler.getTagValue( lookup, TAG_EAT_ROW_ON_FAILURE ) );
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString(
        PKG, "DatabaseLookupMeta.ERROR0001.UnableToLoadStepFromXML" ), e );
    }
  }

  @Override
  public void setDefault() {
    streamKeyField1 = null;
    returnValueField = null;
    databaseMeta = null;
    cached = false;
    cacheSize = 0;
    schemaName = "";
    tablename = BaseMessages.getString( PKG, "DatabaseLookupMeta.Default.TableName" );

    allocate( 0, 0 );

    orderByClause = "";
    failingOnMultipleResults = false;

View on GitHub (pinned to f3058517a1)