pentaho/pentaho-kettle · error · KettleException

FuzzyMatch.Exception.CouldnotFindMainField

Error message

FuzzyMatch.Exception.CouldnotFindMainField

What it means

lookupValues resolves the Main Stream Field against the main input row's metadata (getInputRowMeta) and throws this KettleException when the field is not present (indexOfValue < 0). It guards the main-stream side of the fuzzy match, complementing 1471/1472 which guard the lookup stream.

Solutions

1. Re-select the Main stream field in the Fuzzy Match dialog from the actual available columns.
2. Inspect the main stream layout (preview or 'Input fields') and confirm the field name and spelling.
3. Fix upstream steps to emit the required field before the Fuzzy Match step.
4. If a variable supplies the field name, verify it resolves at runtime.

Example fix

// before
Main stream field: 'cust_name'
// after (actual main-stream column)
Main stream field: 'customer_name'

// Before the Fuzzy Match step, assert the main stream field exists:
int idx = mainRowMeta.indexOfValue(mainStreamFieldName);
if (idx < 0) {
  throw new KettleException("Main stream field not found: " + mainStreamFieldName);
}

try {
  outputRow();
} catch (KettleException e) {
  if (e.getMessage().contains("CouldnotFindMainField")) {
    logError("Main stream field missing — check Fuzzy Match config vs main stream layout: " + e.getMessage());
  }
  throw e;
}

When it happens

Trigger: The configured 'Main stream field' is absent from the main input stream's row metadata on the first call to outputRow/lookupValues.

Common situations: Upstream step renamed/deleted the main-stream column; wrong field selected in the dialog; a previous transformation in a pipeline chain changed the layout; copy/paste of step config between transformations with different schemas.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• FuzzyMatch.Exception.CouldnotFindLookField
• A connection of type PALO is expected
• A server socket allocation always has to accompanied by…
• AccessInput.Exception.CouldnotFindField
• AccessInput.Log.NoField

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/fuzzymatch/FuzzyMatch.java:177

    }

    return true;
  }

  private Object[] lookupValues( RowMetaInterface rowMeta, Object[] row ) throws KettleException {
    if ( first ) {
      first = false;

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields(
        getTransMeta().getBowl(), data.outputRowMeta, getStepname(), new RowMetaInterface[] { data.infoMeta }, null,
        this, repository, metaStore );

      // Check lookup field
      data.indexOfMainField = getInputRowMeta().indexOfValue( environmentSubstitute( meta.getMainStreamField() ) );
      if ( data.indexOfMainField < 0 ) {
        // The field is unreachable !
        throw new KettleException( BaseMessages.getString( PKG, "FuzzyMatch.Exception.CouldnotFindMainField", meta
          .getMainStreamField() ) );
      }
    }
    Object[] add = null;
    if ( row[ data.indexOfMainField ] == null ) {
      add = buildEmptyRow();
    } else {
      try {
        add = getFromCache( row );
      } catch ( Exception e ) {
        throw new KettleStepException( e );
      }
    }
    return RowDataUtil.addRowData( row, rowMeta.size(), add );
  }

  private void addToCache( Object[] value ) throws KettleException {
    try {

View on GitHub (pinned to f3058517a1)