pentaho/pentaho-kettle · error · KettleStepException

DimensionLookup.Exception.KeyFieldNotFound

Error message

DimensionLookup.Exception.KeyFieldNotFound

What it means

During processRow the DimensionLookup step resolves each configured key lookup stream field to its index in the input row metadata. If a key stream field name (meta.getKeyStream()[i]) cannot be found in the incoming rows, indexOfValue returns -1 and this KettleStepException is thrown. The key fields are required to build the dimension lookup condition, so the step cannot proceed without them.

Solutions

  1. Open the DimensionLookup step's Key table and correct each 'Stream field' name to match the actual input fields.
  2. Restore the missing key field upstream (add it back in Table Input / Select Values / previous step).
  3. Re-run 'Get fields' in the step dialog to refresh key mappings against the current input row metadata.
  4. Preview the previous step's output to confirm the key columns exist with exact names before running.

Example fix

// before: key field renamed upstream but step still points at old name
// meta.setKeyStream(new String[] { "CUSTOMER_ID_OLD" });
// after
// meta.setKeyStream(new String[] { "CUSTOMER_ID" });
Defensive patterns

Strategy: validation

Validate before calling

// Before the step (or in meta validation):
// for (String key : meta.getKeyStream()) {
//   if (inputRowMeta.indexOfValue(key) < 0)
//     throw new KettleStepException("Missing key field: " + key);
// }

Try / catch

try {
  // step execution
} catch (KettleStepException e) {
  if (e.getMessage().contains("KeyFieldNotFound")) {
    // the message names the missing field; fix upstream or remap, then rerun
  } else throw e;
}

Prevention

When it happens

Trigger: processRow loops over meta.getKeyStream() and data.inputRowMeta.indexOfValue(keyStream[i]) < 0 for any configured key field — the field is missing from the rows arriving at the step.

Common situations: Upstream field renamed/deleted (e.g. after editing a Select Values or Table Input step); connecting the step to a hop whose rows lack the key columns; case-sensitivity mismatches between configured and actual field names; reusing a saved transformation whose input schema changed.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookup.java:151

      // The start date value column (if applicable)
      //
      data.startDateFieldIndex = -1;
      if ( data.startDateChoice == DimensionLookupMeta.START_DATE_ALTERNATIVE_COLUMN_VALUE ) {
        data.startDateFieldIndex = data.inputRowMeta.indexOfValue( meta.getStartDateFieldName() );
        if ( data.startDateFieldIndex < 0 ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "DimensionLookup.Exception.StartDateValueColumnNotFound", meta.getStartDateFieldName() ) );
        }
      }

      // Lookup values
      data.keynrs = new int[ meta.getKeyStream().length ];
      for ( int i = 0; i < meta.getKeyStream().length; i++ ) {
        // logDetailed("Lookup values key["+i+"] --> "+key[i]+", row==null?"+(row==null));
        data.keynrs[ i ] = data.inputRowMeta.indexOfValue( meta.getKeyStream()[ i ] );
        if ( data.keynrs[ i ] < 0 ) { // couldn't find field!
          throw new KettleStepException( BaseMessages.getString(
            PKG, "DimensionLookup.Exception.KeyFieldNotFound", meta.getKeyStream()[ i ] ) );
        }
      }

      // Return values
      data.fieldnrs = new int[ meta.getFieldStream().length ];
      for ( int i = 0; meta.getFieldStream() != null && i < meta.getFieldStream().length; i++ ) {
        if ( !DimensionLookupMeta.isUpdateTypeWithoutArgument( meta.isUpdate(), meta.getFieldUpdate()[ i ] ) ) {
          data.fieldnrs[ i ] = data.outputRowMeta.indexOfValue( meta.getFieldStream()[ i ] );
          if ( data.fieldnrs[ i ] < 0 ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "DimensionLookup.Exception.KeyFieldNotFound", meta.getFieldStream()[ i ] ) );
          }
        } else {
          data.fieldnrs[ i ] = -1;
        }

      }

View on GitHub (pinned to f3058517a1)