pentaho/pentaho-kettle · error · KettleException

Unknown field specified to replace with a formula result: [

Error message

Unknown field specified to replace with a formula result: [

What it means

KettleException thrown in Formula.processRow() when a formula entry specifies a 'replace field' that does not exist in the incoming row's field metadata. The step resolves the replace field's index via getInputRowMeta().indexOfValue(); a negative index means the field name is misspelled or absent at runtime.

Solutions

  1. Correct the 'Replace value' field name in the Formula step to exactly match an input field (case-sensitive).
  2. Reconnect/re-synchronize the step's hop so the field list refreshes in the dialog.
  3. Ensure the upstream step that creates the field executes before the Formula step.
  4. Use the step's 'Get fields' button to pick an existing field instead of typing it.

Example fix

// before (formula meta)
fn.setReplaceField("amount_old"); // field no longer exists
// after
fn.setReplaceField("amount"); // matches actual input field
Defensive patterns

Strategy: validation

Validate before calling

// before running the transformation
for (FormulaMetaFunction fn : meta.getFormula()) {
  if (!Utils.isEmpty(fn.getReplaceField()) && inputRowMeta.indexOfValue(fn.getReplaceField()) < 0)
    throw new KettleException("Replace field missing: " + fn.getReplaceField());
}

Try / catch

try { return formulaStepData(row); } catch (KettleException e) { log.error("Check replace field names in Formula step: " + e.getMessage()); throw e; }

Prevention

When it happens

Trigger: A Formula step defines formula[i].replaceField, but that field is missing from the input row metadata when the first row arrives — e.g. renamed upstream, not yet produced by a later step, or removed after editing the transform.

Common situations: Reordering steps so the Formula step runs before the field it replaces is created; renaming a CSV column; case-sensitive field name mismatch; replacing a field whose source stream is optional.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/formula/Formula.java:83

      first = false;

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Create the context
      data.context = new RowForumulaContext( data.outputRowMeta );
      data.parser = new FormulaParser();

      // Calculate replace indexes...
      //
      data.replaceIndex = new int[meta.getFormula().length];
      for ( int i = 0; i < meta.getFormula().length; i++ ) {
        FormulaMetaFunction fn = meta.getFormula()[i];
        if ( !Utils.isEmpty( fn.getReplaceField() ) ) {
          data.replaceIndex[i] = getInputRowMeta().indexOfValue( fn.getReplaceField() );
          if ( data.replaceIndex[i] < 0 ) {
            throw new KettleException( "Unknown field specified to replace with a formula result: ["
              + fn.getReplaceField() + "]" );
          }
        } else {
          data.replaceIndex[i] = -1;
        }
      }
    }

    if ( log.isRowLevel() ) {
      logRowlevel( "Read row #" + getLinesRead() + " : " + Arrays.toString( r ) );
    }

    Object[] outputRowData = calcFields( getInputRowMeta(), r );
    putRow( data.outputRowMeta, outputRowData ); // copy row to possible alternate rowset(s).

    if ( log.isRowLevel() ) {
      logRowlevel( "Wrote row #" + getLinesWritten() + " : " + Arrays.toString( r ) );
    }

View on GitHub (pinned to f3058517a1)