pentaho/pentaho-kettle · error · KettleStepException

ScriptMeta.Exception.FieldToReplaceNotFound

Error message

ScriptMeta.Exception.FieldToReplaceNotFound

What it means

In getFields(), when a Script step output field is marked replace=true but the incoming row has no field with that name AND no rename target is set, the step cannot determine which field to replace. It throws KettleStepException 'FieldToReplaceNotFound' naming the field.

Solutions

  1. Correct the field name in the Script step's Fields tab so it matches the actual incoming row field.
  2. If the goal is to create a new field, uncheck 'Replace value' for that field.
  3. Fill in the Rename field to redirect the replacement to the correct target.
  4. Inspect the upstream step's output (View data) to confirm the exact field name.

Example fix

// before (Script step Fields tab config)
fieldname='cust_id', replace=true, rename=''
// after (match upstream field name)
fieldname='customer_id', replace=true, rename=''
Defensive patterns

Strategy: validation

Validate before calling

// In Spoon: preview the upstream step output and confirm field names
// or in code, before executing:
if (replace[i] && row.searchValueMeta(fieldname[i]) == null && Utils.isEmpty(rename[i])) {
  throw new IllegalArgumentException("Field to replace not found: " + fieldname[i]);
}

Try / catch

try { step.getFields(row, ...); } catch (KettleStepException e) {
  if (e.getMessage().contains("FieldToReplaceNotFound")) {
    // uncheck 'replace' or fix the field name in the step dialog
  }
}

Prevention

When it happens

Trigger: Field name in the Script step's output definition (fieldname[i]) does not match any incoming row field while replace[i] is true and rename[i] is empty.

Common situations: Upstream step renamed or dropped the field the script was supposed to overwrite; user typed the wrong field name; change introduced by editing an earlier step in the transformation.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/script/ScriptMeta.java:288

      precision[i] = -1;
      replace[i] = false;
    }
  }

  @Override
  public void getFields( Bowl bowl, RowMetaInterface row, String originStepname, RowMetaInterface[] info, StepMeta nextStep,
    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {
    for ( int i = 0; i < fieldname.length; i++ ) {
      if ( !Utils.isEmpty( fieldname[i] ) ) {
        String fieldName;
        int replaceIndex;
        int fieldType;

        if ( replace[i] ) {
          // Look up the field to replace...
          //
          if ( row.searchValueMeta( fieldname[i] ) == null && Utils.isEmpty( rename[i] ) ) {
            throw new KettleStepException( BaseMessages.getString(
              PKG, "ScriptMeta.Exception.FieldToReplaceNotFound", fieldname[i] ) );
          }
          replaceIndex = row.indexOfValue( rename[i] );

          // Change the data type to match what's specified...
          //
          fieldType = type[i];
          fieldName = rename[i];
        } else {
          replaceIndex = -1;
          fieldType = type[i];
          if ( rename[i] != null && rename[i].length() != 0 ) {
            fieldName = rename[i];
          } else {
            fieldName = fieldname[i];
          }
        }
        try {

View on GitHub (pinned to f3058517a1)