pentaho/pentaho-kettle · error · KettleException

JobGetMailsFromPOP.InvalidFolder.Label

Error message

JobGetMailsFromPOP.InvalidFolder.Label

What it means

openSpecifiedFolder() throws this when the user-requested folder is null after getRecursiveFolder() or does not exist in the store (folder.exists() == false). The configured folder name doesn't match anything on the server.

Solutions

  1. Correct the folder name to the exact server-side path (check in Thunderbird/webmail; IMAP hierarchy delimiter is usually '.').
  2. Verify the folder still exists and the account can see it.
  3. For nested folders use the server's hierarchy delimiter, e.g. INBOX.Archive.2024.
  4. If the folder may be absent, guard with store.getFolder(name) + exists() check before opening.

Example fix

// before
openFolder("inbox/archive", false);
// after (IMAP delimiter is '.')
openFolder("INBOX.Archive", false);
Defensive patterns

Strategy: validation

Validate before calling

mailConnection.connect();
String name = "INBOX.Archive";
javax.mail.Folder f = mailConnection.getStore().getFolder(name);
if (f == null || !f.exists()) {
  throw new KettleException("Folder does not exist on server: " + name);
}

Try / catch

try {
  mailConnection.openFolder(folderName, false);
} catch (KettleException e) {
  logError("Invalid folder '" + folderName + "', check server-side path", e);
  throw e;
}

Prevention

When it happens

Trigger: openFolder(foldername, defaultFolder=false) → openSpecifiedFolder where this.folder == null || !this.folder.exists().

Common situations: Typo in folder name, wrong path separator (IMAP uses '.' or '/' per server), folder renamed/deleted, case-sensitivity differences, mbox directory path wrong.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

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

      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() ) );
      }
      this.folder.open( Folder.READ_WRITE );
    } else {
      if ( log.isDebug() ) {
        log.logDebug( BaseMessages.getString(
          PKG, "MailConnection.OpeningFolderInReadMode.Label", getFolderName() ) );
      }
      this.folder.open( Folder.READ_ONLY );
    }
  }

View on GitHub (pinned to f3058517a1)