pentaho/pentaho-kettle · error · KettleStepException

ERROR0001

ERROR0001

Error message

DatabaseLookup.ERROR0001.FieldRequired5.Exception + keyFields[i] + DatabaseLookup.ERROR0001.FieldRequired6.Exception

What it means

DatabaseLookup.determineFieldsTypesQueryingDb() queries the lookup table metadata and, for each configured key field, looks it up in the resulting table field list via fields.searchValueMeta(keyFields[i]). If the key field is not a column of the lookup table, it throws KettleStepException 'Field required' (FieldRequired5/6) naming the missing key field.

Solutions

Edit the Database Lookup step and set key fields that actually exist as columns in the lookup table
Refresh the step's table-field list after any table schema change
Qualify the table with the correct schema (schema.table) so the right table's columns are read
Re-run the step metadata lookup (preview) to validate field names before executing

Example fix

// before (step config)
keyField = "custumer_id";
// after
keyField = "customer_id"; // must match a real column of the lookup table

Defensive patterns

Strategy: validation

Validate before calling

// validate key fields exist in the lookup table before running the transformation
DatabaseMeta dbMeta = meta.getDatabaseMeta();
RowMetaInterface tableFields = db.getTableFields( meta.getSchemaTable() );
for ( String kf : meta.getKeyField() ) {
  if ( tableFields == null || tableFields.searchValueMeta( kf ) == null ) {
    throw new KettleException( "Lookup key field not a table column: " + kf );
  }
}

Try / catch

try {
  result = step.lookup( row );
} catch ( KettleStepException e ) {
  if ( e.getMessage() != null && e.getMessage().contains( keyFieldName ) ) {
    // refresh table metadata, fix mapping, retry
  } else { throw e; }
}

Prevention

Refresh the Database Lookup step dialog after any table DDL change
Use schema-qualified table names
Add transformation checks (Spoon 'Verify') which report missing field mappings
Preview the lookup step to validate configuration before full runs

When it happens

Trigger: processRow() runs with a lookup that must determine key types from the database (no cached row) and a configured key field (keyFields[i]) does not exist in the schema.table being looked up.

Common situations: Typo in the lookup-table key column name; the lookup table was renamed or its schema changed after the step was configured; the transformation was moved to an environment where the table has different columns.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/databaselookup/DatabaseLookup.java:241

  @VisibleForTesting
  void determineFieldsTypesQueryingDb() throws KettleException {
    final String[] keyFields = meta.getTableKeyField();
    data.keytypes = new int[ keyFields.length ];

    String schemaTable =
      meta.getDatabaseMeta().getQuotedSchemaTableCombination(
        environmentSubstitute( meta.getSchemaName() ), environmentSubstitute( meta.getTablename() ) );

    RowMetaInterface fields = data.db.getTableFields( schemaTable );
    if ( fields != null ) {
      // Fill in the types...
      for ( int i = 0; i < keyFields.length; i++ ) {
        ValueMetaInterface key = fields.searchValueMeta( keyFields[ i ] );
        if ( key != null ) {
          data.keytypes[ i ] = key.getType();
        } else {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "DatabaseLookup.ERROR0001.FieldRequired5.Exception" )
            + keyFields[ i ]
            + BaseMessages.getString( PKG, "DatabaseLookup.ERROR0001.FieldRequired6.Exception" ) );
        }
      }

      if ( shouldDatabaseReturnValueTypeBeUsed() ) {
        useReturnValueTypeFromDatabase( fields );
      }

    } else {
      throw new KettleStepException( BaseMessages.getString(
        PKG, "DatabaseLookup.ERROR0002.UnableToDetermineFieldsOfTable" )
        + schemaTable + "]" );
    }
  }

  /*

View on GitHub (pinned to f3058517a1)