What causes "Unable to connect find mapped value with name '{0}'." in pentaho/pentaho-kettle?

Update the Mapping step's field mappings so sourceValueName matches a real incoming field.

pentaho/pentaho-kettle · error · KettleStepException

MappingInput.Exception.UnableToFindMappedValue

MappingInput.Exception.UnableToFindMappedValue

Error message

Unable to connect find mapped value with name '{0}'.

What it means

During metadata propagation, MappingInputMeta.getFields() applies each MappingValueRename to the input row metadata. If neither the source nor the target field name exists in the input row metadata, it throws this KettleStepException. It means the mapping's rename spec references a field the incoming rows (or the designer's resolved metadata) simply do not contain.

Solutions

Update the Mapping step's field mappings so sourceValueName matches a real incoming field.
Preview the upstream step output in the parent transformation to confirm the field name.
Re-select/regenerate the mapping fields in the Mapping Input step dialog.
Check for case sensitivity or whitespace differences in field names.

Example fix

// before: rename spec for a field that no longer exists
new MappingValueRename("cust_id_old", "customer_id");
// after
new MappingValueRename("cust_id", "customer_id");

Defensive patterns

Strategy: validation

Validate before calling

for (MappingValueRename r : valueRenames) {
  boolean src = inputRowMeta.searchValueMeta(r.getSourceValueName()) != null;
  boolean tgt = inputRowMeta.searchValueMeta(r.getTargetValueName()) != null;
  if (!src && !tgt) {
    throw new IllegalStateException("Mapping references unknown field: " + r.getSourceValueName());
  }
}

Type guard

boolean mappableField(RowMetaInterface meta, MappingValueRename r) {
  return meta.searchValueMeta(r.getSourceValueName()) != null || meta.searchValueMeta(r.getTargetValueName()) != null;
}

Try / catch

try {
  trans.waitUntilFinished();
} catch (KettleStepException e) {
  if (e.getMessage().contains("Unable to connect find mapped value")) {
    // re-sync Mapping step field mappings with upstream fields
  }
  throw e;
}

Prevention

Validate mapping renames against upstream field metadata before execution.
Re-open and re-save the Mapping step after upstream schema changes.
Use 'Get Fields' in the Mapping dialogs rather than manual entry.
Check both source and target names — the library retries with the target name.

When it happens

Trigger: getFields(): inputRowMeta.searchValueMeta(sourceValueName) is null and the retry with targetValueName is also null while iterating valueRenames.

Common situations: Field renamed/deleted upstream after the mapping was saved; wrong sub-transformation selected; missing hop metadata at design time; renamed database columns changing field names before the Mapping Input step.

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

Appendix: source

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

    // That is because there is no previous step to this mapping input step from the viewpoint of this single
    // sub-transformation.
    // From the viewpoint of the transformation that executes the mapping, it's important to know what comes out at the
    // exit points.
    // For that reason we need to re-order etc, based on the input specification...
    //
    if ( inputRowMeta != null && !inputRowMeta.isEmpty() ) {
      // this gets set only in the parent transformation...
      // It includes all the renames that needed to be done
      //
      // First rename any fields...
      if ( valueRenames != null ) {
        for ( MappingValueRename valueRename : valueRenames ) {
          ValueMetaInterface valueMeta = inputRowMeta.searchValueMeta( valueRename.getSourceValueName() );
          if ( valueMeta == null ) {
            // ok, let's search once again, now using target name
            valueMeta = inputRowMeta.searchValueMeta( valueRename.getTargetValueName() );
            if ( valueMeta == null ) {
              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(

View on GitHub (pinned to f3058517a1)