pentaho/pentaho-kettle · error · KettleStepException

DenormaliserMeta.Exception.UnableToLocateKeyField

DenormaliserMeta.Exception.UnableToLocateKeyField

Error message

DenormaliserMeta.Exception.UnableToLocateKeyField

What it means

DenormaliserMeta.getFields transforms the input row metadata for the Denormaliser step. The key field (the grouping field) must exist in the incoming stream and is removed from the output row layout. If keyField is set but not found in the row (indexOfValue returns -1), a KettleStepException is thrown with the field name in the message.

Solutions

  1. Preview the rows entering the Denormaliser and set its 'key field' to a field that actually exists.
  2. Fix upstream renaming/dropping of the key field (Select values, Calculator, etc.).
  3. Re-run the 'Get fields' / verify mapping in the Denormaliser dialog after any upstream change.
  4. If the key field should not exist, note that it is consumed as the grouping key — define it upstream.

Example fix

// before
keyField = "grp_id"  // upstream renamed it
// after
keyField = "group_id" // matches field emitted by the previous step
Defensive patterns

Strategy: validation

Validate before calling

RowMetaInterface input = previousStep.getOutputRowMeta();
if (denormMeta.getKeyField() != null && input.indexOfValue(denormMeta.getKeyField()) < 0) {
  throw new IllegalArgumentException("Key field not in input stream: " + denormMeta.getKeyField());
}

Try / catch

try { transMeta.getFields(...); } catch (KettleStepException e) { log.error("Denormaliser key field missing: {}", e.getMessage(), e); }

Prevention

When it happens

Trigger: getFields (invoked during transformation initialization, e.g. from testGetFields) is given a non-empty keyField that is absent from the incoming RowMetaInterface — row.indexOfValue(keyField) returns -1.

Common situations: Upstream step renamed/removed the key field; typo in the Denormaliser 'key field' setting; changing the stream layout with a Select values step and forgetting to update the Denormaliser.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/denormaliser/DenormaliserMeta.java:164

  }

  public void setDefault() {
    int sizegroup = 0;
    int nrfields = 0;

    allocate( sizegroup, nrfields );
  }

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

    // Remove the key value (there will be different entries for each output row)
    //
    if ( keyField != null && keyField.length() > 0 ) {
      int idx = row.indexOfValue( keyField );
      if ( idx < 0 ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "DenormaliserMeta.Exception.UnableToLocateKeyField", keyField ) );
      }
      row.removeValueMeta( idx );
    } else {
      throw new KettleStepException( BaseMessages.getString( PKG, "DenormaliserMeta.Exception.RequiredKeyField" ) );
    }

    // Remove all field value(s) (there will be different entries for each output row)
    //
    for ( int i = 0; i < denormaliserTargetField.length; i++ ) {
      String fieldname = denormaliserTargetField[i].getFieldName();
      if ( fieldname != null && fieldname.length() > 0 ) {
        int idx = row.indexOfValue( fieldname );
        if ( idx >= 0 ) {
          row.removeValueMeta( idx );
        }
      } else {
        throw new KettleStepException( BaseMessages.getString(

View on GitHub (pinned to f3058517a1)