pentaho/pentaho-kettle · error · KettleStepException

MappingInputMeta.Exception.UnknownField

MappingInputMeta.Exception.UnknownField

Error message

Unable to find field '{0}' in the input rows metadata.

What it means

When the Mapping Input step is configured to select and sort specified fields only, getFields() rebuilds the output row from the fields listed in fieldName[]. If any listed field is not present in the input row metadata (indexOfValue returns -1), this KettleStepException is thrown naming the missing field. It means the step's selected-field list is out of sync with the actual incoming fields.

Solutions

  1. Open the Mapping Input step and remove/correct the field listed in the error message.
  2. Preview the parent hop output and re-select fields from the actual layout.
  3. Enable 'selecting and sorting unspecified fields' appropriately, or clear the explicit field list.
  4. Re-save the sub-transformation after upstream schema changes to refresh metadata.

Example fix

// before: selected field missing upstream
fieldName = new String[] { "id", "legacy_col" };
// after
fieldName = new String[] { "id", "renamed_col" }; // matches upstream
Defensive patterns

Strategy: validation

Validate before calling

if (mappingInputMeta.isSelectingAndSortingUnspecifiedFields()) {
  for (String f : mappingInputMeta.getFieldName()) {
    if (inputRowMeta.indexOfValue(f) < 0) {
      throw new IllegalStateException("Selected field missing upstream: " + f);
    }
  }
}

Type guard

boolean allFieldsPresent(RowMetaInterface meta, String[] fields) {
  return Arrays.stream(fields).allMatch(f -> meta.indexOfValue(f) >= 0);
}

Try / catch

try {
  trans.waitUntilFinished();
} catch (KettleStepException e) {
  if (e.getMessage().contains("Unable to find field")) {
    // remove or rename the field listed in the message in the Mapping Input dialog
  }
  throw e;
}

Prevention

When it happens

Trigger: getFields() with isSelectingAndSortingUnspecifiedFields=true: inputRowMeta.indexOfValue(fieldName[i]) < 0 for an entry of the configured field list.

Common situations: Selecting specific fields in the Mapping Input dialog that the parent doesn't send; upstream schema change removing a selected field; typo'd field name in the step configuration; loading a mapping designed against a different parent transformation.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mappinginput/MappingInputMeta.java:268

              throw new KettleStepException( BaseMessages.getString(
                PKG, "MappingInput.Exception.UnableToFindMappedValue", valueRename.getSourceValueName() ) );
            }
          } else {
            valueMeta.setName( valueRename.getTargetValueName() );
          }
        }
      }

      if ( selectingAndSortingUnspecifiedFields ) {
        // Select the specified fields from the input, re-order everything and put the other fields at the back,
        // sorted...
        //
        RowMetaInterface newRow = new RowMeta();

        for ( int i = 0; i < fieldName.length; i++ ) {
          int index = inputRowMeta.indexOfValue( fieldName[ i ] );
          if ( index < 0 ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "MappingInputMeta.Exception.UnknownField", fieldName[ i ] ) );
          }

          newRow.addValueMeta( inputRowMeta.getValueMeta( index ) );
        }

        // Now get the unspecified fields.
        // Sort the fields
        // Add them after the specified fields...
        //
        List<String> extra = new ArrayList<String>();
        for ( int i = 0; i < inputRowMeta.size(); i++ ) {
          String fieldName = inputRowMeta.getValueMeta( i ).getName();
          if ( newRow.indexOfValue( fieldName ) < 0 ) {
            extra.add( fieldName );
          }
        }
        Collections.sort( extra );

View on GitHub (pinned to f3058517a1)