pentaho/pentaho-kettle · error · KettleException

MailConnection.Error.RetrieveMessages

Error message

MailConnection.Error.RetrieveMessages

What it means

retrieveMessages() wraps exceptions from folder.search(searchTerm) or folder.getMessages() into a KettleException with MailConnection.Error.RetrieveMessages and the folder name, nulling this.messages first. The folder is open but listing or searching its messages failed.

Solutions

  1. Remove/simplify search filters — some protocols (POP3) barely support server-side search.
  2. Verify the session is still alive; reconnect if the mailbox listing times out.
  3. For huge mailboxes, restrict by message count/date instead of fetching all messages.
  4. Ensure retrieveMessages() is called only while the folder is open.

Example fix

// before: search term on POP3
mailConnection.addSearchTerm(new ReceivedDateTerm(GE, cutoff));
mailConnection.retrieveMessages();
// after: filter client-side for POP3
mailConnection.retrieveMessages();
Message[] msgs = mailConnection.getMessages(); // filter in the job entry
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure folder open before retrieving
if (mailConnection.getFolder() == null || !mailConnection.getFolder().isOpen()) {
  mailConnection.openFolder("INBOX", true);
}
// avoid search terms on POP3
boolean supportsSearch = mailConnection.getServerProtocol() != MailConnectionMeta.PROTOCOL_POP3;

Try / catch

try {
  mailConnection.retrieveMessages();
} catch (KettleException e) {
  logError("Failed to list messages in " + mailConnection.getFolderName() + ": " + e.getCause(), e);
  throw e;
}

Prevention

When it happens

Trigger: retrieveMessages() called on an open folder where folder.search() throws (unsupported search term for protocol) or folder.getMessages() throws (connection dropped, folder closed mid-operation).

Common situations: POP3 servers rejecting search terms (POP3 search support is minimal), IMAP session timed out during large mailbox listing, folder closed by another thread/client.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

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

   *
   * @throws KettleException
   */
  public void retrieveMessages() throws KettleException {
    try {
      if ( this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {
        this.messages = this.mboxMessages;
        return;
      }

      // search term?
      if ( this.searchTerm != null ) {
        this.messages = this.folder.search( this.searchTerm );
      } else {
        this.messages = this.folder.getMessages();
      }
    } catch ( Exception e ) {
      this.messages = null;
      throw new KettleException( BaseMessages.getString(
        PKG, "MailConnection.Error.RetrieveMessages", getFolderName() ), e );
    }
  }

  /**
   * Gets the effective message number for a Message.
   * For MBOX messages, this returns the mapped sequence number (1-based).
   * For POP3/IMAP messages, this returns the actual message number from the server.
   */
  public int getEffectiveMessageNumber( Message message ) {
    if ( mboxConnected && mboxMessageNumbers.containsKey( message ) ) {
      return mboxMessageNumbers.get( message );
    }
    try {
      return message.getMessageNumber();
    } catch ( Exception e ) {
      return 0;
    }

View on GitHub (pinned to f3058517a1)