pentaho/pentaho-kettle · error · KettleStepException

Field [ ] is required and couldn't be found!

Error message

Field [{0}] is required and couldn't be found!

What it means

The Update step could not find one of the configured key stream fields in the incoming row metadata during processRow initialization. Since the key is required to build the WHERE clause, it throws KettleStepException naming the missing field via the FieldRequired message.

Solutions

  1. Open the Update step dialog and correct the key field name to one present in the incoming stream
  2. Check the upstream step actually emits the field (run with row metadata logging or 'Preview')
  3. Set the key condition to 'IS NULL'/'IS NOT NULL' only when the field value is genuinely not needed

Example fix

// before
key_stream: customer_id_old
// after
key_stream: customer_id
Defensive patterns

Strategy: validation

Validate before calling

// In a UDJC or via step preview before Update:
if (getInputRowMeta().indexOfValue("customer_id") < 0) throw new KettleStepException("Key field customer_id missing from incoming stream");

Try / catch

try { transformation.start(); } catch (KettleStepException e) { if (e.getMessage().contains("is required and couldn't be found")) { /* fix step mapping and retry */ } }

Prevention

When it happens

Trigger: getInputRowMeta().indexOfValue(meta.getKeyStream()[i]) returns -1 for a key condition other than 'IS NULL'/'IS NOT NULL' (which don't need the field value).

Common situations: Renaming or removing an upstream field used as a lookup key; connecting the wrong stream into the Update step; copy/pasted transformations where the key field is produced by a disabled predecessor 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/2030503ef1414b38. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/update/Update.java:236

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

      // lookup the values!
      if ( log.isDetailed() ) {
        logDetailed( BaseMessages.getString( PKG, "Update.Log.CheckingRow" ) + getInputRowMeta().getString( r ) );
      }

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

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

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

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

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

View on GitHub (pinned to f3058517a1)