pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.ValueReferenceFieldNotSpecified

Error message

TableCompare.Exception.ValueReferenceFieldNotSpecified

What it means

TableCompare.processRow() requires the error-handling 'Value reference' field and throws this KettleException (ValueReferenceFieldNotSpecified) when meta.getValueReferenceField() is empty. Required-configuration guard: the step needs to know which column carries the reference value per row before processing.

Solutions

Enter 'Value reference fieldname' in the TableCompare dialog.
In code, call meta.setValueReferenceField("...") before running the transformation.
Assert all six required field-name settings are non-empty in a pre-run metadata validation.

Example fix

// before
TableCompareMeta meta = new TableCompareMeta();
// ... other fields set ...
// value reference never set
// after
meta.setValueReferenceField( "value_reference" );

Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getValueReferenceField() == null || meta.getValueReferenceField().isEmpty() ) {
  throw new IllegalStateException( "TableCompare: Value reference fieldname is required" );
}

Try / catch

try {
  step.processRow();
} catch ( KettleException e ) {
  if ( String.valueOf( e.getLocalizedMessage() ).contains( "ValueReferenceFieldNotSpecified" ) ) {
    logError( "Set 'Value reference fieldname' in the TableCompare dialog and rerun" );
  }
  setErrors( 1 );
  stopAll();
}

Prevention

Complete all setter calls when constructing TableCompareMeta in code.
Use meta.setDefault() immediately after construction.
Fail fast in CI by validating step metadata before executing transformations.

When it happens

Trigger: Utils.isEmpty(meta.getValueReferenceField()) is true in processRow() — 'Value reference fieldname' is blank in the TableCompare dialog or in code-built metadata.

Common situations: Programmatic metadata construction (as in the calling test) omitting setSetValueReferenceField; incomplete dialog saves; copying steps between transformations where fields were reset.

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/f2de4be24d3dc443. Report an issue: GitHub.

Appendix: source

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

          .getExcludeFieldsField() ) );
      }

      // error handling: Key description
      //
      if ( Utils.isEmpty( meta.getKeyDescriptionField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.KeyDescriptionFieldNotSpecified" ) );
      }
      data.keyDescIndex = getInputRowMeta().indexOfValue( meta.getKeyDescriptionField() );
      if ( data.keyDescIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getKeyDescriptionField() ) );
      }

      // error handling: reference value
      //
      if ( Utils.isEmpty( meta.getValueReferenceField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ValueReferenceFieldNotSpecified" ) );
      }
      data.valueReferenceIndex = getInputRowMeta().indexOfValue( meta.getValueReferenceField() );
      if ( data.valueReferenceIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getValueReferenceField() ) );
      }

      // error handling: compare value
      //
      if ( Utils.isEmpty( meta.getValueCompareField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ValueCompareFieldNotSpecified" ) );
      }
      data.valueCompareIndex = getInputRowMeta().indexOfValue( meta.getValueCompareField() );
      if ( data.valueCompareIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getValueCompareField() ) );

View on GitHub (pinned to f3058517a1)