pentaho/pentaho-kettle · error · KettleException

MailConnection.Error.WriteMboxFile

MailConnection.Error.WriteMboxFile

Error message

MailConnection.Error.WriteMboxFile

What it means

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.

Solutions

  1. Read e.getCause() to distinguish file IO from message serialization failures
  2. Check disk space and write permissions on the target file
  3. Close other applications holding the mbox file open
  4. Retry after reopening the source connection if a message body failed to load

Example fix

// before
connection.writeMessagesToMbox( msgs, path, true ); // may throw
// after
try {
  connection.writeMessagesToMbox( msgs, path, true );
} catch ( KettleException e ) {
  logError( "Mbox write failed for " + path + ": " + e.getCause(), e );
}
Defensive patterns

Strategy: try-catch

Validate before calling

java.io.File target = new java.io.File( targetMboxPath );
if ( target.exists() && !target.canWrite() ) {
  throw new IllegalStateException( "Mbox file not writable: " + targetMboxPath );
}
if ( target.getParentFile() != null && target.getParentFile().getUsableSpace() < requiredBytes ) {
  throw new IllegalStateException( "Insufficient disk space" );
}

Try / catch

try {
  connection.writeMessagesToMbox( msgs, path, true );
} catch ( KettleException e ) {
  logError( "Write to " + path + " failed: " + e.getCause(), e );
  // free disk / unlock file, then retry
}

Prevention

When it happens

Trigger: FileOutputStream/BufferedOutputStream fails (file locked, permission denied, disk full) or writeMessageAsMboxEntry throws IOException/MessagingException while writing headers/body of a source message.

Common situations: Disk quota/full; mbox file opened exclusively by a mail client; source IMAP message content unavailable mid-write; antivirus locking the file on Windows.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

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

  private void appendMessagesToMbox( Message[] sourceMessages, String targetMboxPath ) throws KettleException {
    writeMessagesToMbox( Arrays.asList( sourceMessages ), targetMboxPath, true );
  }

  private void writeMessagesToMbox( List<Message> sourceMessages, String targetMboxPath, boolean append )
    throws KettleException {
    File targetFile = new File( targetMboxPath );
    File parent = targetFile.getParentFile();
    if ( parent != null && !parent.exists() && !parent.mkdirs() ) {
      throw new KettleException( BaseMessages.getString( PKG, ERROR_CREATE_FOLDER, targetMboxPath ) );
    }

    try ( OutputStream outputStream = new BufferedOutputStream( new FileOutputStream( targetFile, append ) ) ) {
      for ( Message sourceMessage : sourceMessages ) {
        writeMessageAsMboxEntry( sourceMessage, outputStream );
      }
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "MailConnection.Error.WriteMboxFile", targetMboxPath ), e );
    }
  }

  private void writeMessageAsMboxEntry( Message sourceMessage, OutputStream outputStream )
    throws IOException, MessagingException {
    writeMessageHeader( sourceMessage, outputStream );
    writeMessageBody( sourceMessage, outputStream );
    outputStream.write( '\n' );
  }

  private void writeMessageHeader( Message sourceMessage, OutputStream outputStream ) throws IOException, MessagingException {
    String header = "From " + getEnvelopeFrom( sourceMessage ) + " " + new Date() + "\n";
    outputStream.write( header.getBytes( StandardCharsets.ISO_8859_1 ) );
  }

  private void writeMessageBody( Message sourceMessage, OutputStream outputStream ) throws IOException, MessagingException {
    try ( MboxEscapingOutputStream escapingStream = new MboxEscapingOutputStream( outputStream ) ) {
      sourceMessage.writeTo( escapingStream );

View on GitHub (pinned to f3058517a1)