pentaho/pentaho-kettle · error · KettleStepException

DimensionLookupMeta.Error.NoTechnicalKeySpecified

Error message

DimensionLookupMeta.Error.NoTechnicalKeySpecified

What it means

During DimensionLookupMeta.check() validation, if the technical/surrogate key field name (keyField) is empty, the step logs the localized message 'No technical key specified' and throws a KettleStepException. The dimension lookup cannot function without a technical key column, so the configuration is rejected at design time.

Solutions

  1. Open the Dimension Lookup step and set the 'Technical key field' in the key fields section
  2. If building metadata in code, call meta.setKeyField("your_surrogate_key") before the transformation runs
  3. If the field was renamed in the table, update the step to the new column name
  4. Re-save the transformation after fixing so check() passes

Example fix

// before
DimensionLookupMeta meta = new DimensionLookupMeta();
meta.setKeyField(null); // throws NoTechnicalKeySpecified
// after
meta.setKeyField("dim_customer_tk");
Defensive patterns

Strategy: validation

Validate before calling

// Java: validate step meta before adding it to a transformation
DimensionLookupMeta meta = ...;
if (meta.getKeyField() == null || meta.getKeyField().trim().isEmpty()) {
  throw new IllegalArgumentException("DimensionLookup requires a technical key field");
}

Try / catch

try {
  stepMeta.check(remarks, transMeta, stepMeta, prev, inputFields, outputFields, metaStore, sp);
} catch (KettleStepException e) {
  if (e.getMessage().contains("NoTechnicalKeySpecified") || e.getMessage().contains("technical key")) {
    meta.setKeyField("dim_tk"); // apply default and re-check
  } else throw e;
}

Prevention

When it happens

Trigger: getChecks()/check() is called (e.g. when saving or verifying the step in Spoon) with meta.getKeyField() empty — the 'Technical key field' box was never filled in.

Common situations: Creating the step programmatically without setting the key field; loading metadata where the key field was cleared; renaming/dropping the surrogate key column and clearing the setting; XML templates missing the key_field tag.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

    // It doesn't make sense to use it in the SCD context but people try it anyway
    //
    for ( ValueMetaInterface valueMeta : row.getValueMetaList() ) {
      valueMeta.setStorageType( ValueMetaInterface.STORAGE_TYPE_NORMAL );

      // Also change the trim type to "None" as this can cause trouble
      // during compare of the data when there are leading/trailing spaces in the target table
      //
      valueMeta.setTrimType( ValueMetaInterface.TRIM_TYPE_NONE );
    }

    // technical key can't be null

    if ( Utils.isEmpty( keyField ) ) {
      String message =
          BaseMessages.getString( PKG, "DimensionLookupMeta.Error.NoTechnicalKeySpecified" );

      logError( message );
      throw new KettleStepException( message );
    }

    ValueMetaInterface v = new ValueMetaInteger( keyField );
    if ( keyRename != null && keyRename.length() > 0 ) {
      v.setName( keyRename );
    }

    v.setLength( 9 );
    v.setPrecision( 0 );
    v.setOrigin( name );
    row.addValueMeta( v );

    // 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...

View on GitHub (pinned to f3058517a1)