What causes "MailInput.Error.ReceivedDateSearchTermEmpty" in pentaho/pentaho-kettle?

Enter a value in the 'received date' field of the MailInput step dialog

pentaho/pentaho-kettle · error · KettleException

MailInput.Error.ReceivedDateSearchTermEmpty

MailInput.Error.ReceivedDateSearchTermEmpty

Error message

MailInput.Error.ReceivedDateSearchTermEmpty

What it means

MailInput.init() validates the 'condition on received date' configuration: when the condition is EQUAL, GREATER, or SMALLER, the single received-date field (ReceivedDate1) must be non-empty; otherwise this KettleException is thrown during step initialization. The library needs a concrete date to build the ReceivedDateTerm search filter.

Solutions

Enter a value in the 'received date' field of the MailInput step dialog
Ensure any ${VARIABLE} used for the date is defined at runtime
Use the expected date format configured in the step
If no date filtering is wanted, set the condition to 'none' instead of leaving the date empty

Example fix

// before
realBeginDate = environmentSubstitute( meta.getReceivedDate1() ); // "" -> throws
// after
String realBeginDate = environmentSubstitute( meta.getReceivedDate1() );
if ( Utils.isEmpty( realBeginDate ) ) {
  realBeginDate = "2024/01/01"; // or fail fast with a clear dialog-level validation
}

Defensive patterns

Strategy: validation

Validate before calling

String realDate = environmentSubstitute( meta.getReceivedDate1() );
if ( meta.getConditionOnReceivedDate() != MailConnectionMeta.CONDITION_DATE_NONE
  && Utils.isEmpty( realDate ) ) {
  throw new IllegalArgumentException( "Received date is required for the selected condition" );
}

Try / catch

try {
  init();
} catch ( KettleException e ) {
  logError( "MailInput init failed: " + e.getMessage() );
  setErrors( 1 );
  stopAll();
}

Prevention

Always pair a date condition with a concrete date value
Define environment variables in kettle.properties before deploying
Use the step dialog's validation; avoid blank-but-selected conditions
Prefer condition 'none' when date filtering is not needed

When it happens

Trigger: Starting the MailInput transformation with 'Condition on received date' set to equal/greater/smaller but the received date field left blank or a variable resolving to empty.

Common situations: Date supplied via environment variable that is undefined in the runtime environment; user configured the condition but forgot the date picker field; copying step metadata between environments losing the date value.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at plugins/email-messages/impl/src/main/java/org/pentaho/di/trans/steps/mailinput/MailInput.java:421

      }
      data.rowlimit = limit;
    }
    Date beginDate = null;
    Date endDate = null;
    SimpleDateFormat df = new SimpleDateFormat( MailInputMeta.DATE_PATTERN );

    // check search terms
    // Received Date
    try {
      String realBeginDate;

      switch ( meta.getConditionOnReceivedDate() ) {
        case MailConnectionMeta.CONDITION_DATE_EQUAL:
        case MailConnectionMeta.CONDITION_DATE_GREATER:
        case MailConnectionMeta.CONDITION_DATE_SMALLER:
          realBeginDate = environmentSubstitute( meta.getReceivedDate1() );
          if ( Utils.isEmpty( realBeginDate ) ) {
            throw new KettleException( BaseMessages.getString(
              PKG, "MailInput.Error.ReceivedDateSearchTermEmpty" ) );
          }
          beginDate = df.parse( realBeginDate );
          break;
        case MailConnectionMeta.CONDITION_DATE_BETWEEN:
          realBeginDate = environmentSubstitute( meta.getReceivedDate1() );
          if ( Utils.isEmpty( realBeginDate ) ) {
            throw new KettleException( BaseMessages.getString(
              PKG, "MailInput.Error.ReceivedDatesSearchTermEmpty" ) );
          }
          beginDate = df.parse( realBeginDate );
          String realEndDate = environmentSubstitute( meta.getReceivedDate2() );
          if ( Utils.isEmpty( realEndDate ) ) {
            throw new KettleException( BaseMessages.getString(
              PKG, "MailInput.Error.ReceivedDatesSearchTermEmpty" ) );
          }
          endDate = df.parse( realEndDate );
          break;

View on GitHub (pinned to f3058517a1)