What causes "Unable to find field : {0}" in pentaho/pentaho-kettle?

Update the mapping definition's value renames to match the actual incoming field names

pentaho/pentaho-kettle · error · KettleStepException

MappingMeta.Exception.UnableToFindField

MappingMeta.Exception.UnableToFindField

Error message

Unable to find field : {0}

What it means

Thrown in MappingMeta.getFields while applying value renames from a mapping definition: searchValueMeta cannot find the source field named in a MappingValueRename within the input row. The rename is a hard requirement — the field must exist or the step fails.

Solutions

Update the mapping definition's value renames to match the actual incoming field names
Check upstream steps (Select Values, renames) that may drop or rename the field
Re-run the Mapping step dialog field mapping after changing the sub-transformation

Example fix

// before
renames.add(new MappingValueRename("old_price", "price")); // upstream now emits 'unit_price'
// after
renames.add(new MappingValueRename("unit_price", "price"));

Defensive patterns

Strategy: validation

Validate before calling

// before applying renames
for (MappingValueRename rename : definition.getValueRenames()) {
  if (inputRowMeta.searchValueMeta(rename.getSourceValueName()) == null) {
    logError("Field missing before rename: " + rename.getSourceValueName());
  }
}

Type guard

boolean allRenameSourcesExist(RowMetaInterface row, List<MappingValueRename> renames) { return renames.stream().allMatch(r -> row.searchValueMeta(r.getSourceValueName()) != null); }

Try / catch

try {
  meta.getFields(...);
} catch (KettleStepException e) {
  logError("Rename source field not found: " + e.getMessage());
  // update the mapping definition's field list
}

Prevention

Re-run the field mapping in the Mapping dialog after upstream schema changes
Avoid renaming/removing fields upstream of a Mapping step without updating its definition
Log the input row fields during development to catch schema drift early

When it happens

Trigger: getFields -> definition.getValueRenames() loop, where valueRename.getSourceValueName() is absent from inputRowMeta (searchValueMeta returns null).

Common situations: Upstream step renamed or dropped a field the mapping definition expects; field removed by a Select Values step; mapping definition stale after the sub-transformation's output changed.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/mapping/MappingMeta.java:457

    /*
     * Before we ask the mapping outputs anything, we should teach the mapping input steps in the sub-transformation
     * about the data coming in...
     */
    for ( MappingIODefinition definition : inputMappings ) {

      RowMetaInterface inputRowMeta;

      if ( definition.isMainDataPath() || Utils.isEmpty( definition.getInputStepname() ) ) {
        // The row metadata, what we pass to the mapping input step
        // definition.getOutputStep(), is "row"
        // However, we do need to re-map some fields...
        //
        inputRowMeta = row.clone();
        if ( !inputRowMeta.isEmpty() ) {
          for ( MappingValueRename valueRename : definition.getValueRenames() ) {
            ValueMetaInterface valueMeta = inputRowMeta.searchValueMeta( valueRename.getSourceValueName() );
            if ( valueMeta == null ) {
              throw new KettleStepException( BaseMessages.getString(
                PKG, "MappingMeta.Exception.UnableToFindField", valueRename.getSourceValueName() ) );
            }
            valueMeta.setName( valueRename.getTargetValueName() );
          }
        }
      } else {
        // The row metadata that goes to the info mapping input comes from the
        // specified step
        // In fact, it's one of the info steps that is going to contain this
        // information...
        //
        String[] infoSteps = getInfoSteps();
        int infoStepIndex = Const.indexOfString( definition.getInputStepname(), infoSteps );
        if ( infoStepIndex < 0 ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "MappingMeta.Exception.UnableToFindMetadataInfo", definition.getInputStepname() ) );
        }
        if ( info[infoStepIndex] != null ) {

View on GitHub (pinned to f3058517a1)