{"record":{"id":"5a030b0faff6de05","repo":"pentaho/pentaho-kettle","slug":"mergerows-exception-unabletofindfieldinreferencestream","errorCode":"MergeRows.Exception.UnableToFindFieldInReferenceStream","errorMessage":"MergeRows.Exception.UnableToFindFieldInReferenceStream","messagePattern":"MergeRows\\.Exception\\.UnableToFindFieldInReferenceStream","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/mergerows/MergeRows.java","lineNumber":106,"sourceCode":"      data.two = getRowFrom( data.twoRowSet );\n\n      try {\n        checkInputLayoutValid( data.oneRowSet.getRowMeta(), data.twoRowSet.getRowMeta() );\n      } catch ( KettleRowException e ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"MergeRows.Exception.InvalidLayoutDetected\" ), e );\n      }\n\n      if ( data.one != null ) {\n        // Find the key indexes:\n        data.keyNrs = new int[ meta.getKeyFields().length ];\n        for ( int i = 0; i < data.keyNrs.length; i++ ) {\n          data.keyNrs[ i ] = data.oneRowSet.getRowMeta().indexOfValue( meta.getKeyFields()[ i ] );\n          if ( data.keyNrs[ i ] < 0 ) {\n            String message =\n              BaseMessages.getString( PKG, \"MergeRows.Exception.UnableToFindFieldInReferenceStream\", meta\n                .getKeyFields()[ i ] );\n            logError( message );\n            throw new KettleStepException( message );\n          }\n        }\n      }\n\n      if ( data.two != null ) {\n        data.valueNrs = new int[ meta.getValueFields().length ];\n        for ( int i = 0; i < data.valueNrs.length; i++ ) {\n          data.valueNrs[ i ] = data.twoRowSet.getRowMeta().indexOfValue( meta.getValueFields()[ i ] );\n          if ( data.valueNrs[ i ] < 0 ) {\n            String message =\n              BaseMessages.getString( PKG, \"MergeRows.Exception.UnableToFindFieldInReferenceStream\", meta\n                .getValueFields()[ i ] );\n            logError( message );\n            throw new KettleStepException( message );\n          }\n        }\n      }\n    }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/mergerows/MergeRows.java#L88-L124","documentation":"Thrown by the Merge Rows step in processRow when a configured key field cannot be found in the reference stream's row metadata (indexOfValue returns < 0). The step resolves the indexes of meta.getKeyFields() in the reference (first) stream to perform the comparison.","triggerScenarios":"Running a transformation where an entry in the Merge Rows step's 'Key fields' list is not a field of the reference (first) input stream; this occurs in processRow before any rows are compared.","commonSituations":"Renaming or removing the key field in the reference branch; swapping the reference and compare inputs; typos in the key field name in the step dialog.","solutions":["Open the Merge Rows step dialog and correct the key field names against the reference stream's field list.","Check the reference input step's output fields (Get Fields / Preview) for renamed or removed columns.","Verify the correct step is connected as the reference (first) input; inputs are positional.","Validate the transformation layout before execution to catch stale field references."],"exampleFix":"// before (meta XML)\n<key_field>cust_id</key_field>\n// after (field was renamed upstream)\n<key_field>customer_id</key_field>","handlingStrategy":"validation","validationCode":"// Java: verify key fields exist in the reference stream\nStepMeta mergeRows = transMeta.findStep(\"Merge Rows\");\nMergeRowsMeta meta = (MergeRowsMeta) mergeRows.getStepMetaInterface();\nRowMetaInterface ref = transMeta.getPrevStepFields(mergeRows, 0);\nfor (String key : meta.getKeyFields()) {\n  if (ref.indexOfValue(key) < 0) {\n    throw new IllegalStateException(\"Key field missing in reference stream: \" + key);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.execute(null);\n} catch (KettleStepException e) {\n  if (e.getMessage().contains(\"UnableToFindFieldInReferenceStream\")) {\n    // correct Merge Rows key-field configuration\n  }\n}","preventionTips":["Pick key fields from the dialog's field list, never free-typed.","Re-check key names after any upstream rename in the reference branch.","Confirm which input is the reference (first) before configuring keys.","Validate the transformation after metadata changes."],"tags":["kettle","merge-rows","field-not-found","row-metadata"],"backgroundTag":"resource-not-found","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"}