{"record":{"id":"7739f5081c1037b8","repo":"pentaho/pentaho-kettle","slug":"mailconnection-defaultfoldercannotholdmessage","errorCode":null,"errorMessage":"MailConnection.DefaultFolderCanNotHoldMessage","messagePattern":"MailConnection\\.DefaultFolderCanNotHoldMessage","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":505,"sourceCode":"    this.folder = null;\n    this.messages = null;\n    this.message = null;\n    this.messagenr = -1;\n  }\n\n  private void openDefaultFolder() throws KettleException, MessagingException {\n    if ( protocol == MailConnectionMeta.PROTOCOL_MBOX ) {\n      this.folder = this.store.getDefaultFolder();\n    } else {\n      this.folder = getRecursiveFolder( MailConnectionMeta.INBOX_FOLDER );\n    }\n\n    if ( this.folder == null ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"JobGetMailsFromPOP.InvalidDefaultFolder.Label\" ) );\n    }\n\n    if ( ( folder.getType() & Folder.HOLDS_MESSAGES ) == 0 ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"MailConnection.DefaultFolderCanNotHoldMessage\" ) );\n    }\n  }\n\n  private void openSpecifiedFolder( String foldername ) throws KettleException, MessagingException {\n    if ( this.protocol == MailConnectionMeta.PROTOCOL_IMAP\n      || this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {\n      this.folder = getRecursiveFolder( foldername );\n    }\n    if ( this.folder == null || !this.folder.exists() ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"JobGetMailsFromPOP.InvalidFolder.Label\" ) );\n    }\n  }\n\n  private void openFolderWithMode() throws MessagingException {\n    if ( this.write ) {\n      if ( log.isDebug() ) {\n        log.logDebug( BaseMessages.getString(\n          PKG, \"MailConnection.OpeningFolderInWriteMode.Label\", getFolderName() ) );","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java#L487-L523","documentation":"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.","triggerScenarios":"openFolder(..., defaultFolder=true) resolves to a folder whose (folder.getType() & Folder.HOLDS_MESSAGES) == 0, e.g. the IMAP root namespace folder.","commonSituations":"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.","solutions":["Target a real mailbox (INBOX or a subfolder) rather than the root/namespace folder.","Enable 'specify folder' and enter the exact folder containing messages.","If recursing, verify getRecursiveFolder() resolves INBOX under the server's namespace prefix."],"exampleFix":"// before: opens namespace root\nopenFolder(null, true);\n// after\nopenFolder(\"INBOX\", false);","handlingStrategy":"validation","validationCode":"// inspect folder type before opening\njavax.mail.Folder f = store.getDefaultFolder();\nif (f == null || (f.getType() & Folder.HOLDS_MESSAGES) == 0) {\n  // pick INBOX or first child folder that HOLDS_MESSAGES instead\n}","typeGuard":null,"tryCatchPattern":"try {\n  mailConnection.openFolder(null, true);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"DefaultFolderCanNotHoldMessage\")) {\n    mailConnection.openFolder(\"INBOX\", false); // real mailbox\n  } else throw e;\n}","preventionTips":["Never target namespace/root folders for message retrieval","Use 'specify folder' mode with a concrete mailbox","Test folder type with Folder.HOLDS_MESSAGES in a pre-check"],"tags":["javamail","imap","folder","kettle","email"],"backgroundTag":"unsupported-operation","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"}