pentaho/pentaho-kettle · error · KettleStepException

Unknown field specified to replace with a formula result

Error message

Unknown field specified to replace with a formula result: [{replaceField}]

What it means

Thrown by JaninoMeta.getFields() (metadata-time row-shape calculation) when a formula is set to replace a field that is not present in the incoming row. This fails transformation validation before execution, mirroring the runtime check in Janino.processRow.

Solutions

Correct the 'Replace value' field name in the Formula step dialog.
Clear 'Replace value' to append a new field instead.
Reconnect the hop to the correct upstream step that emits the field.
Run a transformation check (Ctrl+T verify) to catch all such metadata errors before execution.

Example fix

// before
fn.setReplaceField("amount_old");
// after
fn.setReplaceField("amount");

Defensive patterns

Strategy: validation

Validate before calling

// Metadata-time check mirroring getFields()
if (fn.getReplaceField() != null && !fn.getReplaceField().isEmpty()
    && row.indexOfValue(fn.getReplaceField()) < 0) {
  throw new IllegalStateException("Replace field missing from upstream row: " + fn.getReplaceField());
}

Prevention

Run the transformation check (verify) before scheduling.
Keep upstream field contracts stable; document stream schemas.
Clear 'Replace value' when adding new fields instead of replacing.

When it happens

Trigger: getFields() called by Kettle during transformation layout checking; a JaninoMetaFunction has a non-empty replaceField and row.indexOfValue(replaceField) == -1.

Common situations: Same as the runtime variant: upstream field renamed/deleted, hop rewired to a different stream, transformation opened after another developer changed the upstream Select Values 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/07978762e990a34d. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/janino/JaninoMeta.java:166

      if ( Utils.isEmpty( fn.getReplaceField() ) ) {
        // Not replacing a field.
        if ( !Utils.isEmpty( fn.getFieldName() ) ) {
          // It's a new field!

          try {
            ValueMetaInterface v = ValueMetaFactory.createValueMeta( fn.getFieldName(), fn.getValueType() );
            v.setLength( fn.getValueLength(), fn.getValuePrecision() );
            v.setOrigin( name );
            row.addValueMeta( v );
          } catch ( Exception e ) {
            throw new KettleStepException( e );
          }
        }
      } else {
        // Replacing a field
        int index = row.indexOfValue( fn.getReplaceField() );
        if ( index < 0 ) {
          throw new KettleStepException( "Unknown field specified to replace with a formula result: ["
            + fn.getReplaceField() + "]" );
        }
        // Change the data type etc.
        //
        ValueMetaInterface v = row.getValueMeta( index ).clone();
        v.setLength( fn.getValueLength(), fn.getValuePrecision() );
        v.setOrigin( name );
        row.setValueMeta( index, v ); // replace it
      }
    }
  }

  /**
   * Checks the settings of this step and puts the findings in a remarks List.
   *
   * @param remarks
   *          The list to put the remarks in @see org.pentaho.di.core.CheckResult
   * @param stepMeta

View on GitHub (pinned to f3058517a1)