{"record":{"id":"25e4a573084a852a","repo":"pentaho/pentaho-kettle","slug":"mailconnection-error-setdestination","errorCode":null,"errorMessage":"MailConnection.Error.SetDestination","messagePattern":"MailConnection\\.Error\\.SetDestination","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java","lineNumber":1101,"sourceCode":"  /**\n   * Set destination folder\n   *\n   * @param foldername\n   *          destination foldername\n   * @param createFolder\n   *          flag create folder if needed\n   * @throws KettleException\n   */\n  public void setDestinationFolder( String foldername, boolean createFolder ) throws KettleException {\n    try {\n      if ( this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {\n        this.destinationMboxPath = prepareMboxDestinationPath( foldername, createFolder );\n        return;\n      }\n\n      this.destinationIMAPFolder = getOrCreateImapDestinationFolder( foldername, createFolder );\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, ERROR_SET_DESTINATION, foldername ), e );\n    }\n  }\n\n  private String prepareMboxDestinationPath( String foldername, boolean createFolder ) throws KettleException {\n    String resolvedPath = resolveMboxFolderPath( foldername );\n    File destinationFile = new File( resolvedPath );\n    File parentDirectory = destinationFile.getParentFile();\n    if ( parentDirectory == null ) {\n      return resolvedPath;\n    }\n\n    if ( parentDirectory.exists() && !parentDirectory.isDirectory() ) {\n      throw new KettleException( BaseMessages.getString( PKG, ERROR_CREATE_FOLDER, resolvedPath ) );\n    }\n    if ( !parentDirectory.exists() ) {\n      if ( !createFolder ) {\n        throw new KettleException( BaseMessages.getString( PKG, ERROR_FOLDER_NOT_FOUND, foldername ) );\n      }","sourceCodeStart":1083,"sourceCodeEnd":1119,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java#L1083-L1119","documentation":"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.","triggerScenarios":"Calling setDestinationFolder() with a folder name that cannot be resolved on the MBOX filesystem, or whose IMAP folder cannot be fetched/created via getOrCreateImapDestinationFolder().","commonSituations":"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.","solutions":["Check the foldername spelling and that it matches the server's folder namespace separator (/ vs .).","Set createFolder=true so missing destination folders are created instead of failing.","Verify the mail connection is still alive and the store is connected before calling setDestinationFolder.","Inspect the wrapped cause for the exact JavaMail or filesystem error."],"exampleFix":"// before\nconnection.setDestinationFolder(\"Archive/Old mail\", false); // folder missing\n// after\nconnection.setDestinationFolder(\"Archive/OldMail\", true); // create if absent, correct separator","handlingStrategy":"validation","validationCode":"if (foldername == null || foldername.trim().isEmpty()) { throw new IllegalArgumentException(\"Destination folder name is required\"); }","typeGuard":null,"tryCatchPattern":"try { connection.setDestinationFolder(name, true); } catch (KettleException e) { logError(\"Cannot use destination \" + name + \": \" + e.getCause(), e); }","preventionTips":["Validate the folder name against the server namespace/delimiter before calling","Pass createFolder=true when the destination may not exist","Confirm the store is connected before setting destinations"],"tags":["javamail","imap","mbox","folder-setup"],"backgroundTag":"api-error-response","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}