pentaho/pentaho-kettle · error · KettleXMLException

DatabaseJoinMeta.Exception.UnableToLoadStepInfo

Error message

DatabaseJoinMeta.Exception.UnableToLoadStepInfo

What it means

DatabaseJoinMeta.readData(), called from loadXML while deserializing the step from a .ktr, wraps any parsing exception in KettleXMLException 'DatabaseJoinMeta.Exception.UnableToLoadStepInfo'. It means the step's XML (SQL, parameter fields/types) could not be read, so the step cannot be loaded into the transformation graph.

Solutions

  1. Inspect the chained cause e for the exact XML parse/type-resolution failure.
  2. Open the ktr in the Pentaho version that produced it, or upgrade Spoon to that version.
  3. Fix the XML: ensure each parameter <field> has a valid <name> and a known <type>.
  4. Validate the ktr is well-formed XML (xmllint) and not truncated by git/merge tools.

Example fix

// before: invalid value type in XML
<field><name>p1</name><type>NVARCHAR</type></field>
// after
<field><name>p1</name><type>String</type></field>
Defensive patterns

Strategy: try-catch

Validate before calling

Document doc = XMLHandler.loadXMLFile(ktrFile);
if (doc == null) throw new IllegalArgumentException("ktr is not valid XML: " + ktrFile);
if (XMLHandler.getSubNode(doc, "transformation") == null) throw new IllegalArgumentException("Missing <transformation> root");

Try / catch

try { transMeta = new TransMeta(ktrFile, metaStore); }
catch (KettleXMLException e) {
  if (e.getMessage().contains("UnableToLoadStepInfo")) {
    log.error("DatabaseJoin step XML corrupt", e.getCause());
  }
}

Prevention

When it happens

Trigger: Loading a transformation via TransMeta(filename) / XMLHandler when the <field> subnodes are malformed, a type value cannot be resolved by ValueMetaFactory.getIdForValueMeta, or required nodes (connection, sql, parameter fields) are missing/null causing NPE/parse errors.

Common situations: Hand-edited or truncated ktr files; transformations from a newer Pentaho version with unsupported value-type names; XML corruption during version control merges or download.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/databasejoin/DatabaseJoinMeta.java:233

      databaseMeta = DatabaseMeta.findDatabase( databases, con );
      sql = XMLHandler.getTagValue( stepnode, "sql" );
      outerJoin = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "outer_join" ) );
      replacevars = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "replace_vars" ) );
      rowLimit = Const.toInt( XMLHandler.getTagValue( stepnode, "rowlimit" ), 0 );

      Node param = XMLHandler.getSubNode( stepnode, "parameter" );
      int nrparam = XMLHandler.countNodes( param, "field" );

      allocate( nrparam );

      for ( int i = 0; i < nrparam; i++ ) {
        Node pnode = XMLHandler.getSubNodeByNr( param, "field", i );
        parameterField[i] = XMLHandler.getTagValue( pnode, "name" );
        String ptype = XMLHandler.getTagValue( pnode, "type" );
        parameterType[i] = ValueMetaFactory.getIdForValueMeta( ptype );
      }
    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages
        .getString( PKG, "DatabaseJoinMeta.Exception.UnableToLoadStepInfo" ), e );
    }
  }

  @Override
  public void setDefault() {
    databaseMeta = null;
    rowLimit = 0;
    sql = "";
    outerJoin = false;
    parameterField = null;
    parameterType = null;
    outerJoin = false;
    replacevars = false;

    int nrparam = 0;

    allocate( nrparam );

View on GitHub (pinned to f3058517a1)