pentaho/pentaho-kettle · error · KettleStepException

TableCompareMeta.Exception.NrRecordsReferenceFieldNotSpecifi…

Error message

TableCompareMeta.Exception.NrRecordsReferenceFieldNotSpecified

What it means

Second check in TableCompareMeta.getFields(): the 'number of records reference table' output field (nrRecordsReferenceField) is not specified. The step requires all six count/output field names to be set to build its output row metadata.

Solutions

Set the 'nr records reference field' in the step dialog (e.g. 'nr_records_reference').
In code, call meta.setNrRecordsReferenceField("nr_records_reference") before execution.
Fix the .ktr XML <nr_records_reference_field> tag.

Example fix

// before
meta.setNrErrorsField( "nr_errors" );
// nrRecordsReferenceField left null
// after
meta.setNrErrorsField( "nr_errors" );
meta.setNrRecordsReferenceField( "nr_records_reference" );

Defensive patterns

Strategy: validation

Validate before calling

if ( meta.getNrRecordsReferenceField() == null || meta.getNrRecordsReferenceField().isEmpty() ) {
  meta.setNrRecordsReferenceField( "nr_records_reference" );
}

Try / catch

try {
  meta.getFields( ... );
} catch ( KettleStepException e ) {
  if ( e.getMessage().contains( "NrRecordsReferenceFieldNotSpecified" ) ) {
    meta.setNrRecordsReferenceField( "nr_records_reference" );
  }
}

Prevention

Set all output field names in one helper method so none is forgotten.
Diff generated .ktr XML against a known-good transformation.
Re-check step settings after upgrading Pentaho versions.

When it happens

Trigger: getFields(...) invoked with nrRecordsReferenceField null/empty while nrErrorsField passed its check — thrown at TableCompareMeta.java:377.

Common situations: Programmatic step construction setting only some fields; partially migrated/edited .ktr XML; copy-pasting step config and forgetting the reference-record count field.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/tablecompare/TableCompareMeta.java:377

  }

  @Override
  public Object clone() {
    TableCompareMeta retval = (TableCompareMeta) super.clone();

    return retval;
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface inputRowMeta, String origin, RowMetaInterface[] info,
    StepMeta nextStep, VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {

    if ( Utils.isEmpty( nrErrorsField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrErrorsFieldIsNotSpecified" ) );
    }
    if ( Utils.isEmpty( nrRecordsReferenceField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrRecordsReferenceFieldNotSpecified" ) );
    }
    if ( Utils.isEmpty( nrRecordsCompareField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrRecordsCompareFieldNotSpecified" ) );
    }
    if ( Utils.isEmpty( nrErrorsLeftJoinField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrErrorsLeftJoinFieldNotSpecified" ) );
    }
    if ( Utils.isEmpty( nrErrorsInnerJoinField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrErrorsInnerJoinFieldNotSpecified" ) );
    }
    if ( Utils.isEmpty( nrErrorsRightJoinField ) ) {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "TableCompareMeta.Exception.NrErrorsRightJoinFieldNotSpecified" ) );
    }

View on GitHub (pinned to f3058517a1)