pentaho/pentaho-kettle · error · KettleStepException

Unable to find field

Error message

Unable to find field : {0}

What it means

When computing the Simple Mapping step's input field layout, getFields applies each input MappingIODefinition's value renames: it looks up the source field in the cloned input row metadata and renames it to the target name. If a configured source field does not exist in the incoming row, searchValueMeta returns null and a KettleStepException 'Unable to find field: {0}' is thrown.

Solutions

  1. Open the Simple Mapping step's Input mapping tab and update/remove the rename entry whose source field no longer exists.
  2. Check the upstream step output (right-click hop > Show fields) and align the mapping's source field names exactly, including case.
  3. Refresh/regenerate the step metadata after upstream changes, then re-save the transformation.
  4. If the field is genuinely optional, remove the rename and handle it downstream instead.

Example fix

// before: mapping rename references a removed field
rename: source "cust_id" -> target "customerId"  (upstream now emits "customer_id")
// after
rename: source "customer_id" -> target "customerId"
Defensive patterns

Strategy: validation

Validate before calling

// Check every configured rename source exists in the incoming row before execution
RowMetaInterface inputRow = transMeta.getPrevStepFields(stepMeta);
for (MappingIODefinition def : simpleMappingMeta.getInputMapping()) {
  for (MappingValueRename r : def.getValueRenames()) {
    if (inputRow.searchValueMeta(r.getSourceValueName()) == null) {
      throw new IllegalStateException("Mapping rename source field not in input row: " + r.getSourceValueName());
    }
  }
}

Try / catch

try {
  meta.getFields(row, origin, info, target, repository, metaStore, space);
} catch (KettleStepException e) {
  logError("Field rename refers to a missing input field: " + e.getMessage());
}

Prevention

When it happens

Trigger: getFields() iterates inputMapping.getValueRenames() and valueRename.getSourceValueName() is not present in the parent transformation's incoming row metadata (row is non-empty but lacks that field).

Common situations: Upstream step was changed and a field renamed/deleted so the mapping's configured rename no longer matches; mapping configured against a different data shape (e.g. wrong table or file version); case-sensitive field name mismatch; stale saved metadata after upstream column changes.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/simplemapping/SimpleMappingMeta.java:315

    List<MappingValueRename> inputRenameList = new ArrayList<MappingValueRename>();

    //
    // Before we ask the mapping outputs anything, we should teach the mapping
    // input steps in the sub-transformation about the data coming in...
    //

    RowMetaInterface inputRowMeta;

    // 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 : inputMapping.getValueRenames() ) {
        ValueMetaInterface valueMeta = inputRowMeta.searchValueMeta( valueRename.getSourceValueName() );
        if ( valueMeta == null ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "SimpleMappingMeta.Exception.UnableToFindField", valueRename.getSourceValueName() ) );
        }
        valueMeta.setName( valueRename.getTargetValueName() );
      }
    }

    // What is this mapping input step?
    //
    StepMeta mappingInputStep = mappingTransMeta.findMappingInputStep( null );

    // We're certain it's a MappingInput step...
    //
    MappingInputMeta mappingInputMeta = (MappingInputMeta) mappingInputStep.getStepMetaInterface();

    // Inform the mapping input step about what it's going to receive...
    //
    mappingInputMeta.setInputRowMeta( inputRowMeta );

View on GitHub (pinned to f3058517a1)