{"record":{"id":"409d320ae337896f","repo":"pentaho/pentaho-kettle","slug":"mailconnection-error-retrievemessages","errorCode":null,"errorMessage":"MailConnection.Error.RetrieveMessages","messagePattern":"MailConnection\\.Error\\.RetrieveMessages","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":795,"sourceCode":"   *\n   * @throws KettleException\n   */\n  public void retrieveMessages() throws KettleException {\n    try {\n      if ( this.protocol == MailConnectionMeta.PROTOCOL_MBOX ) {\n        this.messages = this.mboxMessages;\n        return;\n      }\n\n      // search term?\n      if ( this.searchTerm != null ) {\n        this.messages = this.folder.search( this.searchTerm );\n      } else {\n        this.messages = this.folder.getMessages();\n      }\n    } catch ( Exception e ) {\n      this.messages = null;\n      throw new KettleException( BaseMessages.getString(\n        PKG, \"MailConnection.Error.RetrieveMessages\", getFolderName() ), e );\n    }\n  }\n\n  /**\n   * Gets the effective message number for a Message.\n   * For MBOX messages, this returns the mapped sequence number (1-based).\n   * For POP3/IMAP messages, this returns the actual message number from the server.\n   */\n  public int getEffectiveMessageNumber( Message message ) {\n    if ( mboxConnected && mboxMessageNumbers.containsKey( message ) ) {\n      return mboxMessageNumbers.get( message );\n    }\n    try {\n      return message.getMessageNumber();\n    } catch ( Exception e ) {\n      return 0;\n    }","sourceCodeStart":777,"sourceCodeEnd":813,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java#L777-L813","documentation":"retrieveMessages() wraps exceptions from folder.search(searchTerm) or folder.getMessages() into a KettleException with MailConnection.Error.RetrieveMessages and the folder name, nulling this.messages first. The folder is open but listing or searching its messages failed.","triggerScenarios":"retrieveMessages() called on an open folder where folder.search() throws (unsupported search term for protocol) or folder.getMessages() throws (connection dropped, folder closed mid-operation).","commonSituations":"POP3 servers rejecting search terms (POP3 search support is minimal), IMAP session timed out during large mailbox listing, folder closed by another thread/client.","solutions":["Remove/simplify search filters — some protocols (POP3) barely support server-side search.","Verify the session is still alive; reconnect if the mailbox listing times out.","For huge mailboxes, restrict by message count/date instead of fetching all messages.","Ensure retrieveMessages() is called only while the folder is open."],"exampleFix":"// before: search term on POP3\nmailConnection.addSearchTerm(new ReceivedDateTerm(GE, cutoff));\nmailConnection.retrieveMessages();\n// after: filter client-side for POP3\nmailConnection.retrieveMessages();\nMessage[] msgs = mailConnection.getMessages(); // filter in the job entry","handlingStrategy":"try-catch","validationCode":"// ensure folder open before retrieving\nif (mailConnection.getFolder() == null || !mailConnection.getFolder().isOpen()) {\n  mailConnection.openFolder(\"INBOX\", true);\n}\n// avoid search terms on POP3\nboolean supportsSearch = mailConnection.getServerProtocol() != MailConnectionMeta.PROTOCOL_POP3;","typeGuard":null,"tryCatchPattern":"try {\n  mailConnection.retrieveMessages();\n} catch (KettleException e) {\n  logError(\"Failed to list messages in \" + mailConnection.getFolderName() + \": \" + e.getCause(), e);\n  throw e;\n}","preventionTips":["Only filter server-side when the protocol supports it","Reconnect on long-running jobs before listing large mailboxes","Limit retrieval with message-count settings for big folders","Call retrieveMessages only with the folder open"],"tags":["javamail","imap","pop3","search","kettle"],"backgroundTag":"database-query-failed","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"}