pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.ValueCompareFieldNotSpecified

Error message

TableCompare.Exception.ValueCompareFieldNotSpecified

What it means

TableCompare.processRow() requires the error-handling 'Value compare' field and throws this KettleException (ValueCompareFieldNotSpecified) when meta.getValueCompareField() is empty. This is the final required-configuration check in the field-resolution block: the step needs the column carrying the compare value per row.

Solutions

  1. Fill in 'Value compare fieldname' in the TableCompare dialog.
  2. In code, call meta.setValueCompareField("...") — or call meta.setDefault() to populate all required settings.
  3. Add a pre-execution check listing all required field names and failing fast when any is empty.

Example fix

// before
meta.setValueReferenceField( "value_reference" );
// value compare never set -> ValueCompareFieldNotSpecified
// after
meta.setValueCompareField( "value_compare" );
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: Utils.isEmpty(meta.getValueCompareField()) is true in processRow() — 'Value compare fieldname' left blank in the TableCompare dialog or in programmatically constructed metadata.

Common situations: Building TableCompareMeta in tests/metadata injection and stopping before setting the last fields; incomplete dialog save; migration losing error-handling settings.

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

Appendix: source

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

          .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() ) );
      }

    } // end if first

    Object[] fields = compareTables( getInputRowMeta(), r );
    Object[] outputRowData = RowDataUtil.addRowData( r, getInputRowMeta().size(), fields );
    putRow( data.outputRowMeta, outputRowData ); // copy row to output rowset(s);
    return true;
  }

  private Object[] compareTables( RowMetaInterface rowMeta, Object[] r ) throws KettleException {
    try {

View on GitHub (pinned to f3058517a1)