pentaho/pentaho-kettle · error · KettleStepException

DimensionLookupMeta.Exception.UnableToFindReturnField

Error message

DimensionLookupMeta.Exception.UnableToFindReturnField

What it means

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.

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

Example fix

// before: return field 'cust_segment' but table has 'segment'
meta.setFieldLookup(new String[] { "cust_segment" });
// after
meta.setFieldLookup(new String[] { "segment" });
meta.setFieldStream(new String[] { "cust_segment" }); // optional rename on the stream

Defensive patterns

Strategy: validation

Validate before calling

// Java: verify every configured return field exists in the table before running
RowMetaInterface tableFields = db.getTableFields(schemaTable);
for (String field : meta.getFieldLookup()) {
  if (tableFields.searchValueMeta(field) == null)
    throw new IllegalStateException("Return field not in dimension table: " + field);
}

Type guard

// null-check the resolved value meta, mirroring the step's own logic
ValueMetaInterface v = row.searchValueMeta(fieldName);
if (v == null) throw new KettleStepException("Unable to find return field: " + fieldName);

Try / catch

try {
  stepMeta.check(...);
} catch (KettleStepException e) {
  if (e.getMessage().contains("UnableToFindReturnField")) {
    // re-read table fields and re-map return fields in the meta
    meta.setFieldLookup(correctedFields);
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/bc0b02eb2e2c1ef6. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookupMeta.java:790

    // retrieve extra fields on lookup?
    // Don't bother if there are no return values specified.
    if ( !update && fieldLookup.length > 0 ) {
      Database db = null;
      try {
        // Get the rows from the table...
        if ( databaseMeta != null ) {
          db = createDatabaseObject();

          RowMetaInterface extraFields = getDatabaseTableFields( db, schemaName, tableName );

          for ( int i = 0; i < fieldLookup.length; i++ ) {
            v = extraFields.searchValueMeta( fieldLookup[i] );
            if ( v == null ) {
              String message =
                  BaseMessages.getString( PKG, "DimensionLookupMeta.Exception.UnableToFindReturnField",
                      fieldLookup[i] );
              logError( message );
              throw new KettleStepException( message );
            }

            // If the field needs to be renamed, rename
            if ( fieldStream[i] != null && fieldStream[i].length() > 0 ) {
              v.setName( fieldStream[i] );
            }
            v.setOrigin( name );
            row.addValueMeta( v );
          }
        } else {
          String message =
              BaseMessages.getString( PKG, "DimensionLookupMeta.Exception.UnableToRetrieveDataTypeOfReturnField" );
          logError( message );
          throw new KettleStepException( message );
        }
      } catch ( Exception e ) {
        String message =
            BaseMessages.getString( PKG, "DimensionLookupMeta.Exception.UnableToRetrieveDataTypeOfReturnField2" );

View on GitHub (pinned to f3058517a1)