{"record":{"id":"6927ada741f19eb5","repo":"pentaho/pentaho-kettle","slug":"dimensionlookup-exception-keyfieldnotfound","errorCode":null,"errorMessage":"DimensionLookup.Exception.KeyFieldNotFound","messagePattern":"DimensionLookup\\.Exception\\.KeyFieldNotFound","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookup.java","lineNumber":151,"sourceCode":"\n      // The start date value column (if applicable)\n      //\n      data.startDateFieldIndex = -1;\n      if ( data.startDateChoice == DimensionLookupMeta.START_DATE_ALTERNATIVE_COLUMN_VALUE ) {\n        data.startDateFieldIndex = data.inputRowMeta.indexOfValue( meta.getStartDateFieldName() );\n        if ( data.startDateFieldIndex < 0 ) {\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"DimensionLookup.Exception.StartDateValueColumnNotFound\", meta.getStartDateFieldName() ) );\n        }\n      }\n\n      // Lookup values\n      data.keynrs = new int[ meta.getKeyStream().length ];\n      for ( int i = 0; i < meta.getKeyStream().length; i++ ) {\n        // logDetailed(\"Lookup values key[\"+i+\"] --> \"+key[i]+\", row==null?\"+(row==null));\n        data.keynrs[ i ] = data.inputRowMeta.indexOfValue( meta.getKeyStream()[ i ] );\n        if ( data.keynrs[ i ] < 0 ) { // couldn't find field!\n          throw new KettleStepException( BaseMessages.getString(\n            PKG, \"DimensionLookup.Exception.KeyFieldNotFound\", meta.getKeyStream()[ i ] ) );\n        }\n      }\n\n      // Return values\n      data.fieldnrs = new int[ meta.getFieldStream().length ];\n      for ( int i = 0; meta.getFieldStream() != null && i < meta.getFieldStream().length; i++ ) {\n        if ( !DimensionLookupMeta.isUpdateTypeWithoutArgument( meta.isUpdate(), meta.getFieldUpdate()[ i ] ) ) {\n          data.fieldnrs[ i ] = data.outputRowMeta.indexOfValue( meta.getFieldStream()[ i ] );\n          if ( data.fieldnrs[ i ] < 0 ) {\n            throw new KettleStepException( BaseMessages.getString(\n              PKG, \"DimensionLookup.Exception.KeyFieldNotFound\", meta.getFieldStream()[ i ] ) );\n          }\n        } else {\n          data.fieldnrs[ i ] = -1;\n        }\n\n      }","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookup.java#L133-L169","documentation":"During processRow the DimensionLookup step resolves each configured key lookup stream field to its index in the input row metadata. If a key stream field name (meta.getKeyStream()[i]) cannot be found in the incoming rows, indexOfValue returns -1 and this KettleStepException is thrown. The key fields are required to build the dimension lookup condition, so the step cannot proceed without them.","triggerScenarios":"processRow loops over meta.getKeyStream() and data.inputRowMeta.indexOfValue(keyStream[i]) < 0 for any configured key field — the field is missing from the rows arriving at the step.","commonSituations":"Upstream field renamed/deleted (e.g. after editing a Select Values or Table Input step); connecting the step to a hop whose rows lack the key columns; case-sensitivity mismatches between configured and actual field names; reusing a saved transformation whose input schema changed.","solutions":["Open the DimensionLookup step's Key table and correct each 'Stream field' name to match the actual input fields.","Restore the missing key field upstream (add it back in Table Input / Select Values / previous step).","Re-run 'Get fields' in the step dialog to refresh key mappings against the current input row metadata.","Preview the previous step's output to confirm the key columns exist with exact names before running."],"exampleFix":"// before: key field renamed upstream but step still points at old name\n// meta.setKeyStream(new String[] { \"CUSTOMER_ID_OLD\" });\n// after\n// meta.setKeyStream(new String[] { \"CUSTOMER_ID\" });","handlingStrategy":"validation","validationCode":"// Before the step (or in meta validation):\n// for (String key : meta.getKeyStream()) {\n//   if (inputRowMeta.indexOfValue(key) < 0)\n//     throw new KettleStepException(\"Missing key field: \" + key);\n// }","typeGuard":null,"tryCatchPattern":"try {\n  // step execution\n} catch (KettleStepException e) {\n  if (e.getMessage().contains(\"KeyFieldNotFound\")) {\n    // the message names the missing field; fix upstream or remap, then rerun\n  } else throw e;\n}","preventionTips":["Re-run 'Get fields' in the step dialog after any upstream schema change.","Preview the previous step to verify key columns exist.","Avoid ad-hoc renames; use a Select Values step deliberately and update dependents.","Version-control transformations and review diffs to field mappings."],"tags":["kettle","pdi","dimension-lookup","missing-field","step-config"],"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"}