{"record":{"id":"e98f9b51412a7219","repo":"pentaho/pentaho-kettle","slug":"multimergejoin-log-unabletofindreferencestream","errorCode":"MultiMergeJoin.Log.UnableToFindReferenceStream","errorMessage":"MultiMergeJoin.Log.UnableToFindReferenceStream","messagePattern":"MultiMergeJoin\\.Log\\.UnableToFindReferenceStream","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/multimerge/MultiMergeJoin.java","lineNumber":88,"sourceCode":"    TransHopMeta transHopMeta;\n\n    StepIOMetaInterface stepIOMeta = meta.getStepIOMeta();\n    List<StreamInterface> infoStreams = stepIOMeta.getInfoStreams();\n    StreamInterface stream;\n    StepMeta toStepMeta = meta.getParentStepMeta();\n    StepMeta fromStepMeta;\n\n    ArrayList<String> inputStepNameList = new ArrayList<String>();\n    String[] inputStepNames = meta.getInputSteps();\n    String inputStepName;\n\n    for ( int i = 0; i < infoStreams.size(); i++ ) {\n      inputStepName = inputStepNames[i];\n      stream = infoStreams.get( i );\n      fromStepMeta = stream.getStepMeta();\n      if ( fromStepMeta == null ) {\n        //should not arrive here, shoud typically have been caught by init.\n        throw new KettleException(\n          BaseMessages.getString( PKG, \"MultiMergeJoin.Log.UnableToFindReferenceStream\", inputStepName ) );\n      }\n      //check the hop\n      transHopMeta = transMeta.findTransHop( fromStepMeta,  toStepMeta, true );\n      //there is no hop: this is unexpected.\n      if ( transHopMeta == null ) {\n        //should not arrive here, shoud typically have been caught by init.\n        throw new KettleException(\n          BaseMessages.getString( PKG, \"MultiMergeJoin.Log.UnableToFindReferenceStream\", inputStepName ) );\n      } else if ( transHopMeta.isEnabled() ) {\n        inputStepNameList.add( inputStepName );\n      } else {\n        logDetailed( BaseMessages.getString( PKG, \"MultiMergeJoin.Log.IgnoringStep\", inputStepName ) );\n      }\n    }\n\n    int streamSize = inputStepNameList.size();\n    if ( streamSize == 0 ) {","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/multimerge/MultiMergeJoin.java#L70-L106","documentation":"MultiMergeJoin.processFirstRow() iterates its info streams and resolves each input step's metadata. If a stream's StepMeta is null (the configured input step name cannot be resolved to an actual step in the transformation), a KettleException 'UnableToFindReferenceStream' is thrown. The in-code comment notes init() should normally have caught this.","triggerScenarios":"Running a transformation where a MultiMergeJoin input stream's source step name is set but the step does not exist in the transformation graph (e.g. step deleted/renamed after the join was configured), so stream.getStepMeta() returns null.","commonSituations":"Hand-edited or programmatically generated ktr XML referencing a nonexistent step name; renaming an input step without reconnecting the hop; XML import where hop definitions were lost.","solutions":["Open the MultiMergeJoin step dialog, verify every listed input step exists and is connected, then re-save","Fix the transformation XML: correct or remove the stale step reference and re-add the hop","Recreate the hop in Spoon by dragging from the actual input step to the join","Validate the TransMeta programmatically before running (transMeta.checkSteps() / verify all hop sources resolve)"],"exampleFix":"// before (stale reference in generated metadata)\njoinMeta.getMainStepName(); // references \"inputA\" which was renamed to \"inputA2\"\n// after\ntransMeta.findStep( \"inputA2\" ); // update join config to the real step name, reconnect hop, then run","handlingStrategy":"validation","validationCode":"for ( String name : joinMeta.getInputStepNames() ) {\n  if ( transMeta.findStep( name ) == null ) {\n    throw new IllegalStateException( \"MultiMergeJoin references non-existent input step: \" + name );\n  }\n}\ntransMeta.checkSteps(); // also surfaces dangling references","typeGuard":"function allInputsResolve( transMeta, joinMeta ) {\n  return joinMeta.getInfoStreams().every( s => s.getStepMeta() != null );\n}","tryCatchPattern":"try {\n  trans.execute( null );\n  trans.waitUntilFinished();\n} catch ( KettleException e ) {\n  if ( e.getMessage() != null && e.getMessage().contains( \"UnableToFindReferenceStream\" ) ) {\n    // fix stale step reference / reconnect hop in transformation metadata\n  } else { throw e; }\n}","preventionTips":["Avoid hand-editing ktr XML step names; rename via Spoon so references update","After deleting/renaming any input step, re-check every join that referenced it","Run checkSteps() validation before execution","Import transformations with hop verification enabled"],"tags":["kettle","multi-merge-join","transformation","broken-hop"],"backgroundTag":"entity-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"}