pentaho/pentaho-kettle · error · KettleStepException

DimensionLookup.Exception.StartDateValueColumnNotFound

Error message

DimensionLookup.Exception.StartDateValueColumnNotFound

What it means

When the DimensionLookup step is configured with start-date alternative 'value of column', the step locates the start-date source column in the incoming row's row metadata. If that column (meta.getStartDateFieldName()) is absent from the input stream, data.startDateFieldIndex stays -1 and this KettleStepException is thrown, stopping the step.

Solutions

Open the DimensionLookup step and correct the 'Date field of start value' (start date column) name to match the actual incoming field.
Add or rename the column upstream so the input stream supplies the configured start-date field.
Use 'Get fields' in the step dialog to re-sync configured field names with the current input row metadata.
Verify with a preview of the preceding step that the start-date column exists in the row layout.

Example fix

// before: configured column no longer in the stream
// meta.setStartDateFieldName("START_DATE_OLD");
// after: match the real upstream field name
// meta.setStartDateFieldName("START_DATE");

Defensive patterns

Strategy: validation

Validate before calling

// In the step or before it, verify the field exists:
// if (inputRowMeta.indexOfValue(startDateFieldName) < 0) {
//   throw new KettleStepException("Missing start date column: " + startDateFieldName);
// }

Try / catch

try {
  // step execution
} catch (KettleStepException e) {
  if (e.getMessage().contains("StartDateValueColumnNotFound")) {
    // fix the start-date field configuration and restart the transformation
  } else throw e;
}

Prevention

After renaming fields upstream, always re-open DimensionLookup and re-map fields.
Use step previews to confirm input layout before production runs.
Keep field names consistent across environments via naming conventions.
Prefer 'Get fields' over hand-typing field names in the dialog.

When it happens

Trigger: processRow with data.startDateChoice == START_DATE_ALTERNATIVE_COLUMN_VALUE and inputRowMeta.indexOfValue(startDateFieldName) < 0, i.e. the configured 'Date field of start value' column is not present on the incoming rows.

Common situations: Renaming or removing the date column in an upstream step after configuring DimensionLookup; wiring the wrong hop so rows lack the column; copying a transformation between environments where field layouts changed; selecting the start-date column option but never adding the field upstream.

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/a8e4f265bc4e280f. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/dimensionlookup/DimensionLookup.java:140

      // Get the fields that need conversion to normal storage...
      // Modify the storage type of the input data...
      //
      data.lazyList = new ArrayList<Integer>();
      for ( int i = 0; i < data.inputRowMeta.size(); i++ ) {
        ValueMetaInterface valueMeta = data.inputRowMeta.getValueMeta( i );
        if ( valueMeta.isStorageBinaryString() ) {
          data.lazyList.add( i );
          valueMeta.setStorageType( ValueMetaInterface.STORAGE_TYPE_NORMAL );
        }
      }

      // The start date value column (if applicable)
      //
      data.startDateFieldIndex = -1;
      if ( data.startDateChoice == DimensionLookupMeta.START_DATE_ALTERNATIVE_COLUMN_VALUE ) {
        data.startDateFieldIndex = data.inputRowMeta.indexOfValue( meta.getStartDateFieldName() );
        if ( data.startDateFieldIndex < 0 ) {
          throw new KettleStepException( BaseMessages.getString(
            PKG, "DimensionLookup.Exception.StartDateValueColumnNotFound", meta.getStartDateFieldName() ) );
        }
      }

      // Lookup values
      data.keynrs = new int[ meta.getKeyStream().length ];
      for ( int i = 0; i < meta.getKeyStream().length; i++ ) {
        // logDetailed("Lookup values key["+i+"] --> "+key[i]+", row==null?"+(row==null));
        data.keynrs[ i ] = data.inputRowMeta.indexOfValue( meta.getKeyStream()[ i ] );
        if ( data.keynrs[ i ] < 0 ) { // couldn't find field!
          throw new KettleStepException( BaseMessages.getString(
            PKG, "DimensionLookup.Exception.KeyFieldNotFound", meta.getKeyStream()[ i ] ) );
        }
      }

      // Return values
      data.fieldnrs = new int[ meta.getFieldStream().length ];
      for ( int i = 0; meta.getFieldStream() != null && i < meta.getFieldStream().length; i++ ) {

View on GitHub (pinned to f3058517a1)