pentaho/pentaho-kettle · error · KettleStepException

InsertUpdate.Exception.FieldRequired

Error message

InsertUpdate.Exception.FieldRequired

What it means

The Insert/Update step could not find one of the configured key lookup fields in the incoming row stream. It throws KettleStepException during processRow while building the key column indexes used for the lookup WHERE clause, unless the key condition is 'IS NULL' or 'IS NOT NULL' (which need no field).

Solutions

  1. Open the Insert/Update step's 'The key(s) to look up the value(s)' grid and fix each Key Stream field to match an actual incoming field (use Get Fields / field selector).
  2. Check the immediately upstream step's output fields (right-click > Show output fields) and fix the rename/removal there.
  3. If the condition is 'IS NULL'/'IS NOT NULL', no stream field is needed — change the condition if a field is genuinely absent.
  4. Enable field name verification in transformation settings to catch mismatches earlier.

Example fix

// before (metadata references missing field)
keyField.setKeyStream("customer_id_old");
// after
keyField.setKeyStream("customer_id"); // matches field produced by upstream step
Defensive patterns

Strategy: validation

Validate before calling

// before running, verify key stream fields exist in the input row meta
for (InsertUpdateKeyField kf : meta.getKeyFields()) {
  if ("IS NULL".equalsIgnoreCase(kf.getKeyCondition()) || "IS NOT NULL".equalsIgnoreCase(kf.getKeyCondition())) continue;
  if (inputRowMeta.indexOfValue(kf.getKeyStream()) < 0)
    throw new IllegalStateException("Key field missing from stream: " + kf.getKeyStream());
}

Type guard

boolean keyFieldPresent(RowMetaInterface row, String name) {
  return name != null && row.indexOfValue(name) >= 0;
}

Try / catch

try { trans.execute(...); } catch (KettleStepException e) {
  if (e.getMessage().contains("FieldRequired")) { /* re-check key field mappings */ }
  throw e;
}

Prevention

When it happens

Trigger: A key field's Key Stream name in the step metadata does not match any field name in the row arriving at the step (renamed upstream, wrong case, field deleted, or a condition other than IS NULL / IS NOT NULL requiring the field).

Common situations: Upstream step renamed or removed a column; typo in the Key Stream field name; a Select Values or Text File Input changed field names; refactored transformation feeds fewer fields into the step.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — 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/f5c3e650a247ee8e. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdate.java:208

        meta.getDatabaseMeta().getQuotedSchemaTableCombination(
          environmentSubstitute( meta.getSchemaName() ), environmentSubstitute( meta.getTableName() ) );

      // lookup the values!
      if ( log.isDebug() ) {
        logDebug( BaseMessages.getString( PKG, "InsertUpdate.Log.CheckingRow" ) + getInputRowMeta().getString( r ) );
      }

      ArrayList<Integer> keynrs = new ArrayList<Integer>( meta.getKeyFields().length );
      ArrayList<Integer> keynrs2 = new ArrayList<Integer>( meta.getKeyFields().length );

      for ( int i = 0; i < meta.getKeyFields().length; i++ ) {
        int keynr = getInputRowMeta().indexOfValue( meta.getKeyFields()[ i ].getKeyStream() );

        if ( keynr < 0 && // couldn't find field!
          !"IS NULL".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) && // No field needed!
          !"IS NOT NULL".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) // No field needed!
        ) {
          throw new KettleStepException( BaseMessages.getString( PKG, "InsertUpdate.Exception.FieldRequired", meta
            .getKeyFields()[ i ].getKeyStream() ) );
        }
        keynrs.add( keynr );

        // this operator needs two bindings
        if ( "= ~NULL".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) ) {
          keynrs.add( keynr );
          keynrs2.add( -1 );
        }

        int keynr2 = getInputRowMeta().indexOfValue( meta.getKeyFields()[ i ].getKeyStream2() );
        if ( keynr2 < 0 && // couldn't find field!
          "BETWEEN".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) // 2 fields needed!
        ) {
          throw new KettleStepException( BaseMessages.getString( PKG, "InsertUpdate.Exception.FieldRequired", meta
            .getKeyFields()[ i ].getKeyStream2() ) );
        }
        keynrs2.add( keynr2 );

View on GitHub (pinned to f3058517a1)