pentaho/pentaho-kettle · error · KettleException

TableCompare.Exception.ReferenceSchemaNotSpecified

Error message

TableCompare.Exception.ReferenceSchemaNotSpecified

What it means

TableCompare.processRow validates its required input fields before comparing two tables. When the reference schema field name configured in the step metadata is empty, it throws a localized KettleException (TableCompare.Exception.ReferenceSchemaNotSpecified) because it cannot locate which incoming row field holds the reference schema.

Solutions

  1. Open the Table Compare step dialog and set the 'Reference schema field' to a field present in the input stream
  2. If injecting metadata, map the referenceSchemaField key to a non-empty source column
  3. Re-save the transformation to persist the field name
  4. Add a Select values / validation step upstream to guarantee the field exists

Example fix

// before
TableCompareMeta meta = new TableCompareMeta();
meta.setReferenceSchemaField( null ); // throws at runtime
// after
meta.setReferenceSchemaField( "ref_schema" ); // non-empty input field name
Defensive patterns

Strategy: validation

Validate before calling

// before running the transformation, assert the setting exists
if ( meta.getReferenceSchemaField() == null || meta.getReferenceSchemaField().isEmpty() ) {
  throw new IllegalArgumentException( "Reference schema field must be set on TableCompareMeta" );
}

Type guard

boolean hasReferenceSchemaField( TableCompareMeta m ) {
  return m != null && m.getReferenceSchemaField() != null && !m.getReferenceSchemaField().isEmpty();
}

Try / catch

try {
  trans.execute( null );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "ReferenceSchemaNotSpecified" ) ) {
    logError( "Configure the Table Compare reference schema field before running" );
  }
}

Prevention

When it happens

Trigger: processRow runs with meta.getReferenceSchemaField() empty — the step was configured without the 'Reference schema field' setting, or the setting was lost/cleared in the transformation metadata.

Common situations: Building the step programmatically without setting referenceSchemaField, importing an old transformation where the option was never filled, or a metadata-injection run leaving the field unmapped.

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

Appendix: source

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

    if ( r == null ) { // no more input to be expected...

      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;

      // What's the format of the output row?
      //
      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Reference schema
      //
      if ( Utils.isEmpty( meta.getReferenceSchemaField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ReferenceSchemaNotSpecified" ) );
      }
      data.refSchemaIndex = getInputRowMeta().indexOfValue( meta.getReferenceSchemaField() );
      if ( data.refSchemaIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getReferenceSchemaField() ) );
      }

      // Reference table
      //
      if ( Utils.isEmpty( meta.getReferenceTableField() ) ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "TableCompare.Exception.ReferenceTableNotSpecified" ) );
      }
      data.refTableIndex = getInputRowMeta().indexOfValue( meta.getReferenceTableField() );
      if ( data.refTableIndex < 0 ) {
        throw new KettleException( BaseMessages.getString( PKG, "TableCompare.Exception.CanNotFindField", meta
          .getReferenceTableField() ) );

View on GitHub (pinned to f3058517a1)