pentaho/pentaho-kettle · error · KettleStepException

Unable to find field

Error message

Unable to find field [<field>] in the input rows (keyStream)

What it means

During metadata validation (getFields/table-fields resolution in SynchronizeAfterMergeMeta), the step looks up each keyStream[i] field in the previous step's row layout (prev.searchValueMeta). If absent, it throws KettleStepException 'Unable to find field [x] in the input rows'. This is a design-time check mirroring error 2280 but raised while building table field metadata.

Solutions

1. Correct the key stream field names in the step dialog to match the actual upstream fields
2. Add a Select values rename step upstream to produce the expected field names
3. Use 'Get Fields' in the dialog instead of typing names to eliminate typos
4. Preview the previous step to confirm the exact field names at runtime

Example fix

// before
keyStream[0] = "order_id"  (stream has "orderId") -> throw
// after
keyStream[0] = "orderId"
// or upstream rename orderId -> order_id

var m = stepMeta.getStepMetaInterface();
var prev = transMeta.getPrevStepFields(stepMeta);
m.getKeyStream().forEach(function(k) { if (k != null && prev.searchValueMeta(k) == null) throw new Error("Missing key field: " + k); });

function fieldExists(rowMeta, name) { return name != null && rowMeta != null && rowMeta.searchValueMeta(name) != null; }

try { stepMeta.getStepMetaInterface().getFields(prev, "keyFields", rowMetaInterfaces, stepMeta, metaStore, transMeta); }
catch (KettleStepException e) { log.error("Key field mapping invalid: " + e.getMessage()); /* correct mapping then retry */ }

When it happens

Trigger: The step's key field grid references a field that the previous step does not output; typically discovered when opening/validating the step dialog or during transformation compilation (getFields).

Common situations: Deleting or renaming an upstream column after configuration; running the step in a different transformation where the upstream schema differs; typos from manually maintained mappings.

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

• Unable to find field
• StreamLookupMeta.Exception.ReturnValueCanNotBeFound
• At least one slave server is required to be present in…
• BaseStreamStepMeta.CheckResult.ResultStepMissing
• ChangeFileEncoding.Error.TargetFileIsEmpty

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/synchronizeaftermerge/SynchronizeAfterMergeMeta.java:913

    Repository repository, IMetaStore metaStore ) throws KettleStepException {
    SQLStatement retval = new SQLStatement( stepMeta.getName(), databaseMeta, null ); // default: nothing to do!

    if ( databaseMeta != null ) {
      if ( prev != null && prev.size() > 0 ) {
        // Copy the row
        RowMetaInterface tableFields = new RowMeta();

        // Now change the field names
        // the key fields
        if ( keyLookup != null ) {
          for ( int i = 0; i < keyLookup.length; i++ ) {
            ValueMetaInterface v = prev.searchValueMeta( keyStream[i] );
            if ( v != null ) {
              ValueMetaInterface tableField = v.clone();
              tableField.setName( keyLookup[i] );
              tableFields.addValueMeta( tableField );
            } else {
              throw new KettleStepException( "Unable to find field [" + keyStream[i] + "] in the input rows" );
            }
          }
        }
        // the lookup fields
        for ( int i = 0; i < updateLookup.length; i++ ) {
          ValueMetaInterface v = prev.searchValueMeta( updateStream[i] );
          if ( v != null ) {
            ValueMetaInterface vk = tableFields.searchValueMeta( updateStream[i] );
            if ( vk == null ) { // do not add again when already added as key fields
              ValueMetaInterface tableField = v.clone();
              tableField.setName( updateLookup[i] );
              tableFields.addValueMeta( tableField );
            }
          } else {
            throw new KettleStepException( "Unable to find field [" + updateStream[i] + "] in the input rows" );
          }
        }

View on GitHub (pinned to f3058517a1)