pentaho/pentaho-kettle · error · KettleStepException

CombinationLookup.Exception.FieldNotFound

Error message

CombinationLookup.Exception.FieldNotFound

What it means

During first-row initialization, CombinationLookup resolves each configured key field's index in the incoming row. If a key field is absent, it throws a KettleStepException 'FieldNotFound' naming the field, since the dimension lookup cannot proceed without all key values.

Solutions

  1. Open the CombinationLookup dialog and re-select the key fields from the actual upstream stream
  2. Use Get Fields / Preview to confirm upstream field names
  3. Restore the missing field in an upstream step (Calculator, Select Values, etc.)

Example fix

// before: dialog references stale field
keyField[0] = "cust_id";
// after
keyField[0] = "CUSTOMER_ID"; // matches upstream stream field
Defensive patterns

Strategy: validation

Validate before calling

for (String keyField : meta.getKeyField()) {
  if (inputRowMeta.indexOfValue(keyField) < 0) {
    throw new IllegalArgumentException("Missing key field in stream: " + keyField);
  }
}

Try / catch

try { trans.execute(null); trans.waitUntilFinished(); }
catch (KettleStepException e) { log.error("CombinationLookup key field missing: " + e.getMessage()); }

Prevention

When it happens

Trigger: processRow, on the first row, loops meta.getKeyField(); getInputRowMeta().indexOfValue(keyField[i]) returns -1 for any configured key stream field.

Common situations: Upstream rename/drop of a key field; typo in the keyfield table on the dialog; hop reconfiguration after editing upstream steps; CSV input column removed.

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

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/combinationlookup/CombinationLookup.java:347

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      data.schemaTable =
        meta.getDatabaseMeta().getQuotedSchemaTableCombination( data.realSchemaName, data.realTableName );

      determineTechKeyCreation();

      // The indexes of the key values...
      //
      data.keynrs = new int[ meta.getKeyField().length ];

      for ( int i = 0; i < meta.getKeyField().length; i++ ) {
        data.keynrs[ i ] = getInputRowMeta().indexOfValue( meta.getKeyField()[ i ] );
        if ( data.keynrs[ i ] < 0 ) {
          // couldn't find field!
          throw new KettleStepException( BaseMessages.getString(
            PKG, "CombinationLookup.Exception.FieldNotFound", meta.getKeyField()[ i ] ) );
        }
      }

      // Determine for each input field if we want it removed or not.
      //
      data.removeField = new boolean[ getInputRowMeta().size() ];

      // Sort lookup values keys so that we
      //
      for ( int i = 0; i < getInputRowMeta().size(); i++ ) {
        ValueMetaInterface valueMeta = getInputRowMeta().getValueMeta( i );
        // Is this one of the keys?
        int idx = Const.indexOfString( valueMeta.getName(), meta.getKeyField() );
        data.removeField[ i ] = idx >= 0;
      }

      // Determine the metadata row to calculate hashcodes.

View on GitHub (pinned to f3058517a1)