pentaho/pentaho-kettle · error · KettleStepException

DimensionLookup.Exception.IllegalStartDateSelection

Error message

DimensionLookup.Exception.IllegalStartDateSelection

What it means

The step's configured 'date range start' selection is a value that doesn't correspond to any known start-date alternative (system date, null, column value, etc.). In dimInsert, the switch over data.startDateChoice hits default and throws a KettleStepException with the numeric choice code, indicating corrupted/unknown metadata rather than a data problem.

Solutions

1. Reopen the transformation in the Spoon GUI and reselect the 'Date range start' option so the metadata is rewritten
2. Open the .ktr XML and fix/inspect the start-date alternative attribute to a valid value
3. Upgrade Pentaho Data Integration so newer enum values from a newer file version are understood
4. If programmatic metadata is used, set DimensionLookupMeta.startDateAlternative to a valid START_DATE_ALTERNATIVE_* constant

Example fix

// before (ktr XML)
// <start_date_alternative>9</start_date_alternative>
// after
// <start_date_alternative>1</start_date_alternative>  <!-- valid: system date -->
// (or re-select 'System date' in the dialog and save)

// programmatic metadata: validate the choice before use
if (startDateChoice != DimensionLookupMeta.startDateAlternativeNone
 && startDateChoice != DimensionLookupMeta.startDateAlternativeSystemDate
 && startDateChoice != DimensionLookupMeta.startDateAlternativeNull
 && startDateChoice != DimensionLookupMeta.startDateAlternativeColumnValue) {
  throw new IllegalStateException("Illegal start date alternative: " + startDateChoice);
}

boolean isValidStartDateChoice(int choice) {
  return choice >= DimensionLookupMeta.START_DATE_ALTERNATIVE_NONE
      && choice <= DimensionLookupMeta.START_DATE_ALTERNATIVE_COLUMN_VALUE;
}

try {
  dimInsert(rowMeta, row);
} catch (KettleStepException e) {
  if (e.getMessage().contains("IllegalStartDateSelection")) {
    logError("Corrupt start-date metadata; reselect in dialog");
  } else { throw e; }
}

When it happens

Trigger: dimInsert writes the startDate into the insert row; if data.startDateChoice holds a value outside the DimensionLookupMeta.START_DATE_ALTERNATIVE_* constants, the switch falls to default.

Common situations: Hand-edited transformation XML (ktr) with an out-of-range value for the start-date alternative; forward-compatibility issue opening a transformation saved by a newer Pentaho version with new enum values; plugin version mismatch.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• DimensionLookup.Exception.ErrorDetectedInComparingFields
• DimensionLookup.Exception.NullDimensionUpdatedDate
• FileExistsMeta.Exception.UnableToReadStepInfo
• Annotation
• BaseStreamStepMeta.CheckResult.ResultStepMissing

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

Appendix: source

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

        break;
      case DimensionLookupMeta.START_DATE_ALTERNATIVE_SYSDATE:
        // use the time the step execution begins as the date from (passed in as dateFrom).
        // before, the current system time was used. this caused an exclusion of the row in the
        // lookup portion of the step that uses this 'valueDate' and not the current time.
        // the result was multiple inserts for what should have been 1 [PDI-4317]
        insertRow[ insertIndex++ ] = dateFrom;
        break;
      case DimensionLookupMeta.START_DATE_ALTERNATIVE_START_OF_TRANS:
        insertRow[ insertIndex++ ] = getTrans().getStartDate();
        break;
      case DimensionLookupMeta.START_DATE_ALTERNATIVE_NULL:
        insertRow[ insertIndex++ ] = null;
        break;
      case DimensionLookupMeta.START_DATE_ALTERNATIVE_COLUMN_VALUE:
        insertRow[ insertIndex++ ] = inputRowMeta.getDate( row, data.startDateFieldIndex );
        break;
      default:
        throw new KettleStepException( BaseMessages.getString(
          PKG, "DimensionLookup.Exception.IllegalStartDateSelection", Integer.toString( data.startDateChoice ) ) );
    }

    insertRow[ insertIndex++ ] = dateTo;

    for ( int i = 0; i < data.keynrs.length; i++ ) {
      insertRow[ insertIndex++ ] = row[ data.keynrs[ i ] ];
    }
    for ( int i = 0; i < data.fieldnrs.length; i++ ) {
      if ( data.fieldnrs[ i ] >= 0 ) {
        // Ignore last_version, last_updated, etc. These are handled below...
        //
        insertRow[ insertIndex++ ] = row[ data.fieldnrs[ i ] ];
      }
    }
    // The special update fields...
    //
    for ( int i = 0; i < meta.getFieldUpdate().length; i++ ) {

View on GitHub (pinned to f3058517a1)