pentaho/pentaho-kettle · error · KettleXMLException

DimensionLookupMeta.Exception.UnableToLoadStepInfoFromXML

Error message

DimensionLookupMeta.Exception.UnableToLoadStepInfoFromXML

What it means

loadXML() deserializes the step's configuration from the transformation XML (stepnode) using XMLHandler tag reads. If any of those reads or subsequent parsing throws, the whole block is caught and rethrown as a KettleXMLException with the localized 'Unable to load step info from XML' message. It indicates the step's XML representation is malformed or contains values the current code cannot parse.

Solutions

Open the .ktr in Spoon and re-save the step to regenerate valid XML
Inspect the wrapped cause (getCause()) to find the exact tag/value that failed to parse
Compare the step XML block against a working Dimension Lookup step's XML and fix or remove invalid tags (especially start_date_alternative)
Align the file with the Kettle version that will run it, or upgrade the Pentaho/Kettle engine
Restore the transformation from backup if the XML was hand-edited or truncated

Example fix

// before: hand-edited XML with unknown alternative value
<start_date_alternative>tomorrow</start_date_alternative>
// after
<start_date_alternative>system_date</start_date_alternative>

Defensive patterns

Strategy: try-catch

Validate before calling

// Java: sanity-check the step XML before loading
org.w3c.dom.Node stepnode = XMLHandler.getSubNode(transNode, "step");
if (XMLHandler.getTagValue(stepnode, "start_date_alternative") == null
    && "Y".equalsIgnoreCase(XMLHandler.getTagValue(stepnode, "use_start_date_alternative"))) {
  throw new IllegalArgumentException("use_start_date_alternative set but start_date_alternative missing");
}

Try / catch

try {
  meta.loadXML(stepnode, databases, metaStore);
} catch (KettleXMLException e) {
  if (e.getMessage().contains("UnableToLoadStepInfoFromXML")) {
    logError("Bad DimensionLookup XML: " + e.getCause());
    // re-create the step in Spoon or fix/remove the offending tag
  } else throw e;
}

Prevention

Never hand-edit step XML; use Spoon to edit and save
Restore from a version-controlled .ktr when XML was modified externally
Check version compatibility of transformation files with your Kettle engine
Always inspect getCause() — it names the tag/value that failed to parse

When it happens

Trigger: Any exception while reading tags such as key_field, table_name, fields, use_start_date_alternative, start_date_alternative, or start_date_field_name from the step node — e.g. getStartDateAlternative cannot map an unknown string to its enum constant.

Common situations: Transformations authored by newer/older Kettle versions with changed tag names or values; hand-edited or truncated .ktr files; copy-pasted step XML missing required tags; an unrecognized start_date_alternative value.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookupMeta.java:959

      minYear = Const.toInt( XMLHandler.getTagValue( stepnode, "min_year" ), Const.MIN_YEAR );

      keyField = XMLHandler.getTagValue( fields, "return", "name" );
      keyRename = XMLHandler.getTagValue( fields, "return", "rename" );
      autoIncrement = !"N".equalsIgnoreCase( XMLHandler.getTagValue( fields, "return", "use_autoinc" ) );
      versionField = XMLHandler.getTagValue( fields, "return", "version" );

      setTechKeyCreation( XMLHandler.getTagValue( fields, "return", "creation_method" ) );

      cacheSize = Const.toInt( XMLHandler.getTagValue( stepnode, "cache_size" ), -1 );
      preloadingCache = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "preload_cache" ) );
      useBatchUpdate = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "useBatch" ) );

      usingStartDateAlternative =
          "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "use_start_date_alternative" ) );
      startDateAlternative = getStartDateAlternative( XMLHandler.getTagValue( stepnode, "start_date_alternative" ) );
      startDateFieldName = XMLHandler.getTagValue( stepnode, "start_date_field_name" );
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString( PKG,
          "DimensionLookupMeta.Exception.UnableToLoadStepInfoFromXML" ), e );
    }
  }

  @Override
  public void readRep( Repository rep, IMetaStore metaStore, ObjectId id_step, List<DatabaseMeta> databases )
    throws KettleException {
    try {
      this.databases = databases;
      databaseMeta = rep.loadDatabaseMetaFromStepAttribute( id_step, "id_connection", databases );

      schemaName = rep.getStepAttributeString( id_step, "schema" );
      tableName = rep.getStepAttributeString( id_step, "table" );
      commitSize = (int) rep.getStepAttributeInteger( id_step, "commit" );
      update = rep.getStepAttributeBoolean( id_step, "update" );

      int nrkeys = rep.countNrStepAttributes( id_step, "lookup_key_name" );
      int nrfields = rep.countNrStepAttributes( id_step, "field_update" );

View on GitHub (pinned to f3058517a1)