pentaho/pentaho-kettle · error · KettleException

JobGetMailsFromPOP.Error.ReceivedDateSearchTermEmpty

JobGetMailsFromPOP.Error.ReceivedDateSearchTermEmpty

Error message

JobGetMailsFromPOP.Error.ReceivedDateSearchTermEmpty

What it means

In JobEntryGetPOP.execute(), when the condition on the received date is EQUAL, GREATER, or SMALLER, the environment-substituted ReceivedDate1 is validated; if empty, a KettleException keyed 'JobGetMailsFromPOP.Error.ReceivedDateSearchTermEmpty' is thrown before SimpleDateFormat.parse is attempted. A date search term requires a concrete date value.

Solutions

Enter a date in the 'Received Date 1' field in the format the entry expects (e.g. yyyy/MM/dd HH:mm:ss)
If using a variable, ensure it is defined (kettle.properties or a Set Variables entry) and non-empty
Switch the date condition to 'between' only when both dates will be provided

Example fix

// before
<received_date_1>${START_DATE}</received_date_1> <!-- unset -->
// after
// kettle.properties: START_DATE=2024/01/01 00:00:00
<received_date_1>2024/01/01 00:00:00</received_date_1>

Defensive patterns

Strategy: validation

Validate before calling

// before executing, mirror the entry's check:
String d = receivedDate1 == null ? null : receivedDate1.replaceAll("\\$\\{[^}]+\\}", "");
if (condition != null && !"between".equalsIgnoreCase(condition) && (d == null || d.trim().isEmpty())) {
  throw new IllegalArgumentException("ReceivedDate1 required for condition " + condition);
}

Try / catch

try { result = jobEntry.execute(prevResult, ...); } catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("ReceivedDateSearchTermEmpty")) {
    log.error("Provide a date for the received-date condition (or clear the condition)");
  }
}

Prevention

Fill in 'Received Date 1' whenever a date condition other than none/between is chosen
Confirm date variables are set before the job entry runs
Use a consistent date format matching the entry's parser (e.g. yyyy/MM/dd HH:mm:ss)

When it happens

Trigger: JobEntryGetPOP (public execute) with getConditionOnReceivedDate() in {EQUAL, GREATER, SMALLER} and the substituted getReceivedDate1() being null/blank.

Common situations: User chose a date condition (e.g. 'greater than') but left the date field blank; a variable like ${MAIL_START_DATE} is undefined so substitution produces an empty string.

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

Appendix: source

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

      if ( getProtocol().equals( MailConnectionMeta.PROTOCOL_STRING_IMAP )
        && ( getActionType() == MailConnectionMeta.ACTION_TYPE_MOVE )
        || ( getActionType() == MailConnectionMeta.ACTION_TYPE_GET
        && getAfterGetIMAP() == MailConnectionMeta.AFTER_GET_IMAP_MOVE ) ) {
        if ( Utils.isEmpty( realMoveToIMAPFolder ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "JobGetMailsFromPOP.Error.MoveToIMAPFolderEmpty" ) );
        }
        moveAfter = true;
      }
      // 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;

View on GitHub (pinned to f3058517a1)