{"record":{"id":"0c5d4387b7fc8170","repo":"pentaho/pentaho-kettle","slug":"streamlookupmeta-exception-returnvaluecannotbefound","errorCode":null,"errorMessage":"StreamLookupMeta.Exception.ReturnValueCanNotBeFound","messagePattern":"StreamLookupMeta\\.Exception\\.ReturnValueCanNotBeFound","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/streamlookup/StreamLookupMeta.java","lineNumber":224,"sourceCode":"    setUsingSortedList( false );\n    setUsingIntegerPair( false );\n\n    allocate( 0, 0 );\n  }\n\n  @Override\n  public void getFields( Bowl bowl, RowMetaInterface row, String origin, RowMetaInterface[] info, StepMeta nextStep,\n    VariableSpace space, Repository repository, IMetaStore metaStore ) throws KettleStepException {\n    if ( info != null && info.length == 1 && info[0] != null ) {\n      for ( int i = 0; i < getValueName().length; i++ ) {\n        ValueMetaInterface v = info[0].searchValueMeta( getValue()[i] );\n        if ( v != null ) {\n          // Configuration error/missing resources...\n          v.setName( getValueName()[i] );\n          v.setOrigin( origin );\n          row.addValueMeta( v );\n        } else {\n          throw new KettleStepException( BaseMessages.getString( PKG,\n              \"StreamLookupMeta.Exception.ReturnValueCanNotBeFound\", getValue()[i] ) );\n        }\n      }\n    } else {\n      for ( int i = 0; i < getValueName().length; i++ ) {\n        try {\n          ValueMetaInterface v = ValueMetaFactory.createValueMeta( getValueName()[i], getValueDefaultType()[i] );\n          v.setOrigin( origin );\n          row.addValueMeta( v );\n        } catch ( Exception e ) {\n          throw new KettleStepException( e );\n        }\n      }\n    }\n  }\n\n  @Override\n  public String getXML() {","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/streamlookup/StreamLookupMeta.java#L206-L242","documentation":"In StreamLookupMeta.getFields, when the lookup value's ValueMeta cannot be found (the configured return field does not exist in the lookup stream's metadata), the step throws ReturnValueCanNotBeFound. This is configuration-time field resolution: the step cannot add the return field to the output row because the source metadata is missing.","triggerScenarios":"getFields looks up getValue()[i] in the info stream's row metadata; v == null triggers the throw because the return field doesn't exist in the lookup stream.","commonSituations":"Value field renamed/deleted upstream after configuration; hop order changed so getFields runs before the source step's fields are known; typo in the return field name; transformation metadata not refreshed (no hop connections defined when getFields runs).","solutions":["Open the StreamLookup step, press 'Get lookup fields', and re-select the return fields from the actual lookup stream","Ensure the hop from the source step to the lookup input exists so its field metadata is available","Correct the <value> field name in the step metadata / ktr XML","Fix the upstream step so it actually emits the configured return field"],"exampleFix":"// before\n<value>amount_toto</value>\n// after\n<value>amount_total</value>","handlingStrategy":"validation","validationCode":"// Before getFields, verify each return field exists in the info stream metadata\nfor (String v : meta.getValue()) {\n  if (infoRowMeta.searchValueMeta(v) == null)\n    throw new IllegalStateException(\"Return field not found in lookup stream: \" + v);\n}","typeGuard":"boolean returnFieldsExist(RowMetaInterface infoMeta, String[] values) {\n  return infoMeta != null && Arrays.stream(values)\n    .allMatch(v -> infoMeta.searchValueMeta(v) != null);\n}","tryCatchPattern":"try { meta.getFields(inputRowMeta, origin, infoRowMeta, ...); }\ncatch (KettleStepException e) {\n  if (e.getMessage().contains(\"ReturnValueCanNotBeFound\")) { /* refresh step metadata */ }\n  throw e;\n}","preventionTips":["Click 'Get lookup fields' after any upstream change and re-save the transformation","Ensure hops are connected before relying on getFields-derived output layout","Fix typos by selecting fields from the dialog list instead of typing names","Run a transformation preview to catch metadata resolution problems early"],"tags":["kettle","pdi","stream-lookup","metadata","field-not-found"],"backgroundTag":"record-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"}