pentaho/pentaho-kettle · error · KettleException

JobGetMailsFromPOP.Error.ReceivedDatesSearchTermEmpty

JobGetMailsFromPOP.Error.ReceivedDatesSearchTermEmpty

Error message

JobGetMailsFromPOP.Error.ReceivedDatesSearchTermEmpty

What it means

In the 'Get Mails (POP3/IMAP)' job entry, when the condition on the received date is BETWEEN, both a begin date and an end date search term are required. The entry resolves each date field through environmentSubstitute() and throws this KettleException if the resolved begin date (getReceivedDate1()) is empty. It exists to fail fast before parsing dates or opening the mail connection.

Solutions

Open the job entry dialog and enter a begin date in the 'First date' field (format matching the entry's date format, e.g. yyyy/MM/dd HH:mm:ss).
If a variable is used, define it at runtime (kettle.properties, -param:START_DATE=..., or Set Variables entry) so it resolves non-empty.
Change the condition on received date from 'between' to a single-date condition (equal/greater/smaller) or 'not between' if only one bound is meaningful.

Example fix

// before (kjb XML metadata)
<received_date_1></received_date_1>
// after
<received_date_1>2024/01/01 00:00:00</received_date_1>

Defensive patterns

Strategy: validation

Validate before calling

String begin = environmentSubstitute(getReceivedDate1());
if (getConditionOnReceivedDate() == MailConnectionMeta.CONDITION_DATE_BETWEEN
    && (begin == null || begin.trim().isEmpty())) {
  throw new IllegalArgumentException("Received-date 'between' requires a non-empty begin date");
}

Try / catch

try { executeJobEntry(); } catch (KettleException e) {
  if (e.getMessage().contains("ReceivedDatesSearchTermEmpty")) {
    logError("Begin/End received date is empty; fix the job entry or define the variable");
  } else { throw e; }
}

Prevention

Always fill both date fields when the condition is 'between'.
Avoid variables in date fields unless they are guaranteed set in every runtime (kitchen, CI, prod).
Validate the saved kjb in a smoke test job before scheduling.

When it happens

Trigger: execute() is called with getConditionOnReceivedDate() == CONDITION_DATE_BETWEEN and environmentSubstitute(getReceivedDate1()) returns null or an empty string — i.e. the 'First date' field is blank or its variable resolves to empty.

Common situations: User selects 'between' for the received-date condition but never fills in the begin date; a variable like ${START_DATE} is used but not defined in the runtime environment (kitchen/pan without the -param or variable set); XML/kjb metadata migrated from another environment with an empty field.

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

Appendix: source

Thrown at plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/JobEntryGetPOP.java:1098

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

      String realServer = getRealServername();
      String realUsername = getRealUsername();
      String realPassword = getRealPassword( getPassword() );
      String realFilenamePattern = getRealFilenamePattern();

View on GitHub (pinned to f3058517a1)