pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.KeyDescriptionFieldNotSpecified

Error message

TableCompare.Exception.KeyDescriptionFieldNotSpecified

What it means

TableCompare.processRow() validates that the error-handling 'Key description' field is configured and throws this KettleException (KeyDescriptionFieldNotSpecified) when meta.getKeyDescriptionField() is empty. This is a required-configuration check: the step writes a key description string per row, so the target column name must be set up front.

Solutions

Fill in 'Key description fieldname' in the TableCompare dialog.
In code, call meta.setKeyDescriptionField("...") with a column that exists in the input stream.
Run meta.setDefault() after construction to ensure all required settings are populated before execution.

Example fix

// before
meta.setCompareTableField( "compare_table" );
meta.setKeyFieldsField( "key_fields" );
meta.setExcludeFieldsField( "exclude_fields" ); // key description missing
// after
meta.setKeyDescriptionField( "key_description" );

Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getKeyDescriptionField() == null || meta.getKeyDescriptionField().isEmpty() ) {
  throw new IllegalStateException( "TableCompare: Key description fieldname is required" );
}

Try / catch

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

Prevention

Don't overlook error-handling output fields — they are required, not optional.
Use meta.setDefault() when building metadata programmatically.
Add a startup validator that checks all six TableCompare field settings.

When it happens

Trigger: Utils.isEmpty(meta.getKeyDescriptionField()) is true in processRow() — 'Key description fieldname' left blank in the TableCompare dialog or in programmatically built metadata.

Common situations: Building TableCompareMeta in tests or via metadata injection and setting only some fields; forgetting error-handling outputs while filling comparison inputs; a dialog saved with defaults that leave error-handling fields empty.

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

Appendix: source

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

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

      // 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() ) );

View on GitHub (pinned to f3058517a1)