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: [+fn.getReplaceField()+]

What it means

KettleStepException thrown in FormulaMeta.getFields() during metadata resolution when a formula is configured to replace a field that does not exist in the incoming row layout. Unlike error 1461 (runtime row processing), this fires earlier while computing output fields from the input row meta.

Solutions

1. Fix the 'Replace value' field name in the Formula dialog to match an existing input field.
2. Re-select the field via the dialog's field picker after changing upstream steps.
3. Use the transformation validator to catch dangling field references before execution.
4. If the field may be absent, add a Select Values step to define a default field first.

Example fix

// before
fn.setReplaceField("total_amt");
// after
fn.setReplaceField("total_amount"); // actual upstream field name

// design-time check mirroring getFields()
for (FormulaMetaFunction fn : meta.getFormula()) {
  if (!Utils.isEmpty(fn.getReplaceField()) && rowMeta.indexOfValue(fn.getReplaceField()) < 0)
    remarks.add(new CheckResult(CheckResultInterface.TYPE_RESULT_ERROR, "Missing replace field: " + fn.getReplaceField(), stepMeta));
}

When it happens

Trigger: FormulaMetaFunction.replaceField is set but row.indexOfValue(replaceField) returns -1 when resolving fields against the input row meta — misspelled field, hop changed, or upstream field removed.

Common situations: Deleting a calculator field upstream and forgetting to update the Formula replace reference; plugging the Formula step onto a different stream; case-sensitivity mismatch in field names.

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

• ERROR_INVALID_ARGUMENT
• MultiMergeJoin.Exception.UnableToFindFieldInReferenceStream
• ScriptValuesMetaMod.Exception.FieldToReplaceNotFound
• throw new KettleStepException( e );
• Unknown field specified to replace with a formula result: [

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/formula/FormulaMeta.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)