{"record":{"id":"bc0b02eb2e2c1ef6","repo":"pentaho/pentaho-kettle","slug":"dimensionlookupmeta-exception-unabletofindreturnfield","errorCode":null,"errorMessage":"DimensionLookupMeta.Exception.UnableToFindReturnField","messagePattern":"DimensionLookupMeta\\.Exception\\.UnableToFindReturnField","errorType":"exception","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookupMeta.java","lineNumber":790,"sourceCode":"    // retrieve extra fields on lookup?\n    // Don't bother if there are no return values specified.\n    if ( !update && fieldLookup.length > 0 ) {\n      Database db = null;\n      try {\n        // Get the rows from the table...\n        if ( databaseMeta != null ) {\n          db = createDatabaseObject();\n\n          RowMetaInterface extraFields = getDatabaseTableFields( db, schemaName, tableName );\n\n          for ( int i = 0; i < fieldLookup.length; i++ ) {\n            v = extraFields.searchValueMeta( fieldLookup[i] );\n            if ( v == null ) {\n              String message =\n                  BaseMessages.getString( PKG, \"DimensionLookupMeta.Exception.UnableToFindReturnField\",\n                      fieldLookup[i] );\n              logError( message );\n              throw new KettleStepException( message );\n            }\n\n            // If the field needs to be renamed, rename\n            if ( fieldStream[i] != null && fieldStream[i].length() > 0 ) {\n              v.setName( fieldStream[i] );\n            }\n            v.setOrigin( name );\n            row.addValueMeta( v );\n          }\n        } else {\n          String message =\n              BaseMessages.getString( PKG, \"DimensionLookupMeta.Exception.UnableToRetrieveDataTypeOfReturnField\" );\n          logError( message );\n          throw new KettleStepException( message );\n        }\n      } catch ( Exception e ) {\n        String message =\n            BaseMessages.getString( PKG, \"DimensionLookupMeta.Exception.UnableToRetrieveDataTypeOfReturnField2\" );","sourceCodeStart":772,"sourceCodeEnd":808,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookupMeta.java#L772-L808","documentation":"During check(), the step verifies each configured lookup/return field against the fields of the dimension table read from the database. When searchValueMeta(fieldLookup[i]) returns null — i.e. a configured return field does not exist in the table's row metadata — the localized 'Unable to find return field' message is logged and a KettleStepException is thrown.","triggerScenarios":"getFields()/check() reads the table's RowMetaInterface from the repository/database and one of the entries in the step's return fields (fieldLookup) has no matching column in the table.","commonSituations":"The dimension table column was renamed or dropped after the step was configured; typo in the field name; connecting to a different database/schema at design time than intended; case-sensitivity mismatch on identifiers.","solutions":["Open the step, open the return-fields grid, and correct or remove the field that no longer exists in the table","Verify you are connected to the intended schema/table when the step reads metadata","Re-read the table fields in the dialog ('Get fields') and re-map the return fields","If the column was renamed in the DB, update the step (or use the field stream alias) accordingly"],"exampleFix":"// before: return field 'cust_segment' but table has 'segment'\nmeta.setFieldLookup(new String[] { \"cust_segment\" });\n// after\nmeta.setFieldLookup(new String[] { \"segment\" });\nmeta.setFieldStream(new String[] { \"cust_segment\" }); // optional rename on the stream","handlingStrategy":"validation","validationCode":"// Java: verify every configured return field exists in the table before running\nRowMetaInterface tableFields = db.getTableFields(schemaTable);\nfor (String field : meta.getFieldLookup()) {\n  if (tableFields.searchValueMeta(field) == null)\n    throw new IllegalStateException(\"Return field not in dimension table: \" + field);\n}","typeGuard":"// null-check the resolved value meta, mirroring the step's own logic\nValueMetaInterface v = row.searchValueMeta(fieldName);\nif (v == null) throw new KettleStepException(\"Unable to find return field: \" + fieldName);","tryCatchPattern":"try {\n  stepMeta.check(...);\n} catch (KettleStepException e) {\n  if (e.getMessage().contains(\"UnableToFindReturnField\")) {\n    // re-read table fields and re-map return fields in the meta\n    meta.setFieldLookup(correctedFields);\n  } else throw e;\n}","preventionTips":["Use 'Get fields' in the step dialog instead of typing field names manually","Re-validate steps after any DDL change (rename/drop columns)","Ensure design-time and run-time connections point to the same schema","Use the step's check() remarks as a pre-deployment gate"],"tags":["configuration","validation","field-mapping","dimension-lookup"],"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"}