{"record":{"id":"f5c3e650a247ee8e","repo":"pentaho/pentaho-kettle","slug":"insertupdate-exception-fieldrequired","errorCode":null,"errorMessage":"InsertUpdate.Exception.FieldRequired","messagePattern":"InsertUpdate\\.Exception\\.FieldRequired","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdate.java","lineNumber":208,"sourceCode":"        meta.getDatabaseMeta().getQuotedSchemaTableCombination(\n          environmentSubstitute( meta.getSchemaName() ), environmentSubstitute( meta.getTableName() ) );\n\n      // lookup the values!\n      if ( log.isDebug() ) {\n        logDebug( BaseMessages.getString( PKG, \"InsertUpdate.Log.CheckingRow\" ) + getInputRowMeta().getString( r ) );\n      }\n\n      ArrayList<Integer> keynrs = new ArrayList<Integer>( meta.getKeyFields().length );\n      ArrayList<Integer> keynrs2 = new ArrayList<Integer>( meta.getKeyFields().length );\n\n      for ( int i = 0; i < meta.getKeyFields().length; i++ ) {\n        int keynr = getInputRowMeta().indexOfValue( meta.getKeyFields()[ i ].getKeyStream() );\n\n        if ( keynr < 0 && // couldn't find field!\n          !\"IS NULL\".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) && // No field needed!\n          !\"IS NOT NULL\".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) // No field needed!\n        ) {\n          throw new KettleStepException( BaseMessages.getString( PKG, \"InsertUpdate.Exception.FieldRequired\", meta\n            .getKeyFields()[ i ].getKeyStream() ) );\n        }\n        keynrs.add( keynr );\n\n        // this operator needs two bindings\n        if ( \"= ~NULL\".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) ) {\n          keynrs.add( keynr );\n          keynrs2.add( -1 );\n        }\n\n        int keynr2 = getInputRowMeta().indexOfValue( meta.getKeyFields()[ i ].getKeyStream2() );\n        if ( keynr2 < 0 && // couldn't find field!\n          \"BETWEEN\".equalsIgnoreCase( meta.getKeyFields()[ i ].getKeyCondition() ) // 2 fields needed!\n        ) {\n          throw new KettleStepException( BaseMessages.getString( PKG, \"InsertUpdate.Exception.FieldRequired\", meta\n            .getKeyFields()[ i ].getKeyStream2() ) );\n        }\n        keynrs2.add( keynr2 );","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/insertupdate/InsertUpdate.java#L190-L226","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["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).","Check the immediately upstream step's output fields (right-click > Show output fields) and fix the rename/removal there.","If the condition is 'IS NULL'/'IS NOT NULL', no stream field is needed — change the condition if a field is genuinely absent.","Enable field name verification in transformation settings to catch mismatches earlier."],"exampleFix":"// before (metadata references missing field)\nkeyField.setKeyStream(\"customer_id_old\");\n// after\nkeyField.setKeyStream(\"customer_id\"); // matches field produced by upstream step","handlingStrategy":"validation","validationCode":"// before running, verify key stream fields exist in the input row meta\nfor (InsertUpdateKeyField kf : meta.getKeyFields()) {\n  if (\"IS NULL\".equalsIgnoreCase(kf.getKeyCondition()) || \"IS NOT NULL\".equalsIgnoreCase(kf.getKeyCondition())) continue;\n  if (inputRowMeta.indexOfValue(kf.getKeyStream()) < 0)\n    throw new IllegalStateException(\"Key field missing from stream: \" + kf.getKeyStream());\n}","typeGuard":"boolean keyFieldPresent(RowMetaInterface row, String name) {\n  return name != null && row.indexOfValue(name) >= 0;\n}","tryCatchPattern":"try { trans.execute(...); } catch (KettleStepException e) {\n  if (e.getMessage().contains(\"FieldRequired\")) { /* re-check key field mappings */ }\n  throw e;\n}","preventionTips":["Click Get Fields in the step dialog after any upstream field name change.","Use the field selector rather than typing field names manually.","Enable field name verification in transformation settings.","Review upstream Select Values/renames whenever editing key mappings."],"tags":["kettle","pdi","field-mapping","schema-mismatch"],"backgroundTag":"missing-required-argument","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}