{"record":{"id":"0aef15556fec609c","repo":"pentaho/pentaho-kettle","slug":"mailconnection-error-writemboxfile","errorCode":"MailConnection.Error.WriteMboxFile","errorMessage":"MailConnection.Error.WriteMboxFile","messagePattern":"MailConnection\\.Error\\.WriteMboxFile","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":1788,"sourceCode":"\n  private void appendMessagesToMbox( Message[] sourceMessages, String targetMboxPath ) throws KettleException {\n    writeMessagesToMbox( Arrays.asList( sourceMessages ), targetMboxPath, true );\n  }\n\n  private void writeMessagesToMbox( List<Message> sourceMessages, String targetMboxPath, boolean append )\n    throws KettleException {\n    File targetFile = new File( targetMboxPath );\n    File parent = targetFile.getParentFile();\n    if ( parent != null && !parent.exists() && !parent.mkdirs() ) {\n      throw new KettleException( BaseMessages.getString( PKG, ERROR_CREATE_FOLDER, targetMboxPath ) );\n    }\n\n    try ( OutputStream outputStream = new BufferedOutputStream( new FileOutputStream( targetFile, append ) ) ) {\n      for ( Message sourceMessage : sourceMessages ) {\n        writeMessageAsMboxEntry( sourceMessage, outputStream );\n      }\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"MailConnection.Error.WriteMboxFile\", targetMboxPath ), e );\n    }\n  }\n\n  private void writeMessageAsMboxEntry( Message sourceMessage, OutputStream outputStream )\n    throws IOException, MessagingException {\n    writeMessageHeader( sourceMessage, outputStream );\n    writeMessageBody( sourceMessage, outputStream );\n    outputStream.write( '\\n' );\n  }\n\n  private void writeMessageHeader( Message sourceMessage, OutputStream outputStream ) throws IOException, MessagingException {\n    String header = \"From \" + getEnvelopeFrom( sourceMessage ) + \" \" + new Date() + \"\\n\";\n    outputStream.write( header.getBytes( StandardCharsets.ISO_8859_1 ) );\n  }\n\n  private void writeMessageBody( Message sourceMessage, OutputStream outputStream ) throws IOException, MessagingException {\n    try ( MboxEscapingOutputStream escapingStream = new MboxEscapingOutputStream( outputStream ) ) {\n      sourceMessage.writeTo( escapingStream );","sourceCodeStart":1770,"sourceCodeEnd":1806,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/email-messages/impl/src/main/java/org/pentaho/di/job/entries/getpop/MailConnection.java#L1770-L1806","documentation":"writeMessagesToMbox() wraps any Exception raised while opening/writing the target mbox file or serializing messages into it, with the target path in the message. It means the mbox file could not be written or a message could not be converted to an mbox entry.","triggerScenarios":"FileOutputStream/BufferedOutputStream fails (file locked, permission denied, disk full) or writeMessageAsMboxEntry throws IOException/MessagingException while writing headers/body of a source message.","commonSituations":"Disk quota/full; mbox file opened exclusively by a mail client; source IMAP message content unavailable mid-write; antivirus locking the file on Windows.","solutions":["Read e.getCause() to distinguish file IO from message serialization failures","Check disk space and write permissions on the target file","Close other applications holding the mbox file open","Retry after reopening the source connection if a message body failed to load"],"exampleFix":"// before\nconnection.writeMessagesToMbox( msgs, path, true ); // may throw\n// after\ntry {\n  connection.writeMessagesToMbox( msgs, path, true );\n} catch ( KettleException e ) {\n  logError( \"Mbox write failed for \" + path + \": \" + e.getCause(), e );\n}","handlingStrategy":"try-catch","validationCode":"java.io.File target = new java.io.File( targetMboxPath );\nif ( target.exists() && !target.canWrite() ) {\n  throw new IllegalStateException( \"Mbox file not writable: \" + targetMboxPath );\n}\nif ( target.getParentFile() != null && target.getParentFile().getUsableSpace() < requiredBytes ) {\n  throw new IllegalStateException( \"Insufficient disk space\" );\n}","typeGuard":null,"tryCatchPattern":"try {\n  connection.writeMessagesToMbox( msgs, path, true );\n} catch ( KettleException e ) {\n  logError( \"Write to \" + path + \" failed: \" + e.getCause(), e );\n  // free disk / unlock file, then retry\n}","preventionTips":["Ensure no mail client holds the mbox open exclusively","Monitor free disk space where mbox archives are written","Whitelist the Pentaho process in antivirus file-locking rules"],"tags":["kettle","pdi","email","mbox","io","file-write"],"backgroundTag":"file-write-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"}