pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.ReferenceTableNotSpecified

Error message

TableCompare.Exception.ReferenceTableNotSpecified

What it means

TableCompare.processRow requires the reference table field to be configured. When meta.getReferenceTableField() is empty it throws TableCompare.Exception.ReferenceTableNotSpecified because it cannot know which input field carries the reference table name.

Solutions

  1. Set the 'Reference table field' in the step dialog to an existing input field
  2. Map referenceTableField during metadata injection
  3. Persist the change by saving the transformation
  4. Verify with a preview that the field is populated on incoming rows

Example fix

// before
meta.setReferenceTableField( "" ); // throws
// after
meta.setReferenceTableField( "ref_table" );
Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getReferenceTableField() == null || meta.getReferenceTableField().isEmpty() ) {
  throw new IllegalArgumentException( "Reference table field must be set on TableCompareMeta" );
}

Type guard

boolean hasReferenceTableField( TableCompareMeta m ) {
  return m != null && m.getReferenceTableField() != null && !m.getReferenceTableField().isEmpty();
}

Try / catch

try {
  trans.execute( null );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "ReferenceTableNotSpecified" ) ) {
    logError( "Set the Table Compare reference table field" );
  }
}

Prevention

When it happens

Trigger: processRow executes with the step's 'Reference table field' setting blank — never set, cleared, or not injected.

Common situations: Programmatic step construction omitting setReferenceTableField, template transformations with unfilled settings, or metadata injection mapping missing the table field key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tablecompare/TableCompare.java:90

      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Reference schema
      //
      if ( Utils.isEmpty( meta.getReferenceSchemaField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ReferenceSchemaNotSpecified" ) );
      }
      data.refSchemaIndex = getInputRowMeta().indexOfValue( meta.getReferenceSchemaField() );
      if ( data.refSchemaIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getReferenceSchemaField() ) );
      }

      // Reference table
      //
      if ( Utils.isEmpty( meta.getReferenceTableField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ReferenceTableNotSpecified" ) );
      }
      data.refTableIndex = getInputRowMeta().indexOfValue( meta.getReferenceTableField() );
      if ( data.refTableIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getReferenceTableField() ) );
      }

      // Compare schema
      //
      if ( Utils.isEmpty( meta.getCompareSchemaField() ) ) {
        throw new KettleException( BaseMessages
          .getString( PKG, "TableCompare.Exception.CompareSchemaNotSpecified" ) );
      }
      data.cmpSchemaIndex = getInputRowMeta().indexOfValue( meta.getCompareSchemaField() );
      if ( data.cmpSchemaIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getCompareSchemaField() ) );

View on GitHub (pinned to f3058517a1)