pentaho/pentaho-kettle · error · KettleException

MailConnection.DefaultFolderCanNotHoldMessage

Error message

MailConnection.DefaultFolderCanNotHoldMessage

What it means

openDefaultFolder() throws this when the resolved default folder exists but its type lacks Folder.HOLDS_MESSAGES — i.e. it is a container/namespace folder that can only hold other folders, not messages. You cannot search or getMessages() on it.

Solutions

  1. Target a real mailbox (INBOX or a subfolder) rather than the root/namespace folder.
  2. Enable 'specify folder' and enter the exact folder containing messages.
  3. If recursing, verify getRecursiveFolder() resolves INBOX under the server's namespace prefix.

Example fix

// before: opens namespace root
openFolder(null, true);
// after
openFolder("INBOX", false);
Defensive patterns

Strategy: validation

Validate before calling

// inspect folder type before opening
javax.mail.Folder f = store.getDefaultFolder();
if (f == null || (f.getType() & Folder.HOLDS_MESSAGES) == 0) {
  // pick INBOX or first child folder that HOLDS_MESSAGES instead
}

Try / catch

try {
  mailConnection.openFolder(null, true);
} catch (KettleException e) {
  if (e.getMessage().contains("DefaultFolderCanNotHoldMessage")) {
    mailConnection.openFolder("INBOX", false); // real mailbox
  } else throw e;
}

Prevention

When it happens

Trigger: openFolder(..., defaultFolder=true) resolves to a folder whose (folder.getType() & Folder.HOLDS_MESSAGES) == 0, e.g. the IMAP root namespace folder.

Common situations: IMAP accounts where the default folder is a namespace root; users pointing the entry at a parent folder like 'INBOX.' prefix root instead of an actual mailbox.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    this.folder = null;
    this.messages = null;
    this.message = null;
    this.messagenr = -1;
  }

  private void openDefaultFolder() throws KettleException, MessagingException {
    if ( protocol == MailConnectionMeta.PROTOCOL_MBOX ) {
      this.folder = this.store.getDefaultFolder();
    } else {
      this.folder = getRecursiveFolder( MailConnectionMeta.INBOX_FOLDER );
    }

    if ( this.folder == null ) {
      throw new KettleException( BaseMessages.getString( PKG, "JobGetMailsFromPOP.InvalidDefaultFolder.Label" ) );
    }

    if ( ( folder.getType() & Folder.HOLDS_MESSAGES ) == 0 ) {
      throw new KettleException( BaseMessages.getString( PKG, "MailConnection.DefaultFolderCanNotHoldMessage" ) );
    }
  }

  private void openSpecifiedFolder( String foldername ) throws KettleException, MessagingException {
    if ( this.protocol == MailConnectionMeta.PROTOCOL_IMAP
      || this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {
      this.folder = getRecursiveFolder( foldername );
    }
    if ( this.folder == null || !this.folder.exists() ) {
      throw new KettleException( BaseMessages.getString( PKG, "JobGetMailsFromPOP.InvalidFolder.Label" ) );
    }
  }

  private void openFolderWithMode() throws MessagingException {
    if ( this.write ) {
      if ( log.isDebug() ) {
        log.logDebug( BaseMessages.getString(
          PKG, "MailConnection.OpeningFolderInWriteMode.Label", getFolderName() ) );

View on GitHub (pinned to f3058517a1)