pentaho/pentaho-kettle · error · KettleException

MailConnection.Error.SetDestination

Error message

MailConnection.Error.SetDestination

What it means

MailConnection.setDestinationFolder(foldername, createFolder) wraps any failure while resolving or creating the destination folder into a KettleException with key MailConnection.Error.SetDestination and the folder name. It covers both protocols: resolving the MBOX destination path and getting/creating the IMAP destination folder. The cause (JavaMail MessagingException, invalid path, IO error) is attached.

Solutions

  1. Check the foldername spelling and that it matches the server's folder namespace separator (/ vs .).
  2. Set createFolder=true so missing destination folders are created instead of failing.
  3. Verify the mail connection is still alive and the store is connected before calling setDestinationFolder.
  4. Inspect the wrapped cause for the exact JavaMail or filesystem error.

Example fix

// before
connection.setDestinationFolder("Archive/Old mail", false); // folder missing
// after
connection.setDestinationFolder("Archive/OldMail", true); // create if absent, correct separator
Defensive patterns

Strategy: validation

Validate before calling

if (foldername == null || foldername.trim().isEmpty()) { throw new IllegalArgumentException("Destination folder name is required"); }

Try / catch

try { connection.setDestinationFolder(name, true); } catch (KettleException e) { logError("Cannot use destination " + name + ": " + e.getCause(), e); }

Prevention

When it happens

Trigger: Calling setDestinationFolder() with a folder name that cannot be resolved on the MBOX filesystem, or whose IMAP folder cannot be fetched/created via getOrCreateImapDestinationFolder().

Common situations: Typo in the destination folder name; IMAP server rejects the namespace (e.g. paths under a non-existent parent hierarchy); destination path points outside an allowed area; server connection dropped mid-operation.

Related errors

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

Appendix: source

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

  /**
   * Set destination folder
   *
   * @param foldername
   *          destination foldername
   * @param createFolder
   *          flag create folder if needed
   * @throws KettleException
   */
  public void setDestinationFolder( String foldername, boolean createFolder ) throws KettleException {
    try {
      if ( this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {
        this.destinationMboxPath = prepareMboxDestinationPath( foldername, createFolder );
        return;
      }

      this.destinationIMAPFolder = getOrCreateImapDestinationFolder( foldername, createFolder );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, ERROR_SET_DESTINATION, foldername ), e );
    }
  }

  private String prepareMboxDestinationPath( String foldername, boolean createFolder ) throws KettleException {
    String resolvedPath = resolveMboxFolderPath( foldername );
    File destinationFile = new File( resolvedPath );
    File parentDirectory = destinationFile.getParentFile();
    if ( parentDirectory == null ) {
      return resolvedPath;
    }

    if ( parentDirectory.exists() && !parentDirectory.isDirectory() ) {
      throw new KettleException( BaseMessages.getString( PKG, ERROR_CREATE_FOLDER, resolvedPath ) );
    }
    if ( !parentDirectory.exists() ) {
      if ( !createFolder ) {
        throw new KettleException( BaseMessages.getString( PKG, ERROR_FOLDER_NOT_FOUND, foldername ) );
      }

View on GitHub (pinned to f3058517a1)