What causes "TableCompare.Exception.ExcludeFieldsNotSpecified" in pentaho/pentaho-kettle?

Set 'Exclude fields fieldname' in the TableCompare dialog to a field in the input stream.

pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.ExcludeFieldsNotSpecified

Error message

TableCompare.Exception.ExcludeFieldsNotSpecified

What it means

TableCompare.processRow() requires the 'Exclude fields' setting and throws this KettleException (ExcludeFieldsNotSpecified) when meta.getExcludeFieldsField() is empty. This is a required-configuration guard, identical in shape to the KeyFieldsNotSpecified check. Without the exclude-fields column the step cannot know which fields to omit from comparison per row.

Solutions

Set 'Exclude fields fieldname' in the TableCompare dialog to a field in the input stream.
In code, call meta.setExcludeFieldsField("...") before execution; consider meta.setDefault() to populate required defaults.
Add a pre-execution metadata check that asserts every required field-name setting is non-empty.

Example fix

// before
TableCompareMeta meta = new TableCompareMeta();
meta.setCompareTableField( "compare_table" );
meta.setKeyFieldsField( "key_fields" ); // exclude fields never set
// after
meta.setExcludeFieldsField( "exclude_fields" );

Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getExcludeFieldsField() == null || meta.getExcludeFieldsField().isEmpty() ) {
  throw new IllegalStateException( "TableCompare: Exclude fields fieldname is required" );
}

Try / catch

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

Prevention

Set every required field name when constructing TableCompareMeta in tests or injected metadata.
Run meta.setDefault() to fill defaults before execution.
Validate transformation metadata at load time rather than at row-processing time.

When it happens

Trigger: Utils.isEmpty(meta.getExcludeFieldsField()) is true in processRow() — the 'Exclude fields fieldname' entry in the TableCompare dialog is blank or null when the transform starts.

Common situations: Programmatic construction of TableCompareMeta (tests, metadata injection) skipping setExcludeFieldsField(); a dialog saved incompletely; migrating transformations where the setting was lost.

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

Appendix: source

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

        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getCompareTableField() ) );
      }

      // Key fields
      //
      if ( Utils.isEmpty( meta.getKeyFieldsField() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.KeyFieldsNotSpecified" ) );
      }
      data.keyFieldsIndex = getInputRowMeta().indexOfValue( meta.getKeyFieldsField() );
      if ( data.keyFieldsIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getKeyFieldsField() ) );
      }

      // Exclude fields
      //
      if ( Utils.isEmpty( meta.getExcludeFieldsField() ) ) {
        throw new KettleException( BaseMessages
          .getString( PKG, "TableCompare.Exception.ExcludeFieldsNotSpecified" ) );
      }
      data.excludeFieldsIndex = getInputRowMeta().indexOfValue( meta.getExcludeFieldsField() );
      if ( data.excludeFieldsIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .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() ) );

View on GitHub (pinned to f3058517a1)