pentaho/pentaho-kettle · error · KettleException

MailConnection.Error.SavingMessageContent

Error message

MailConnection.Error.SavingMessageContent

What it means

saveMessageContentToFile() wraps exceptions from opening the output stream via KettleVFS and writing message.writeTo(os) into a KettleException with MailConnection.Error.SavingMessageContent, including message number, filename and target folder. It means an email could not be exported to disk.

Solutions

  1. Create the target directory beforehand and verify write permissions for the Pentaho user.
  2. Check free disk space and quota on the export volume.
  3. Sanitize the generated filename (strip illegal characters like : ? * | on Windows).
  4. Inspect the chained cause to distinguish VFS open failure vs message writeTo failure.

Example fix

// before
File dir = new File("/exports/mail");
mailConnection.saveMessageContentToFile("msg.eml", "/exports/mail");
// after
dir.mkdirs();
mailConnection.saveMessageContentToFile("msg.eml", "/exports/mail");
Defensive patterns

Strategy: validation

Validate before calling

java.io.File dir = new java.io.File(targetFolder);
if (!dir.isDirectory()) dir.mkdirs();
if (!dir.canWrite()) throw new KettleException("No write permission: " + targetFolder);
String safeName = filename.replaceAll("[/\\\\:*?\"<>|]", "_");

Try / catch

try {
  mailConnection.saveMessageContentToFile(filename, targetFolder);
} catch (KettleException e) {
  logError("Could not save message " + msgNr + " to " + targetFolder + ": " + e.getCause().getMessage(), e);
  throw e;
}

Prevention

When it happens

Trigger: saveMessageContentToFile(filename, foldername) when the VFS output stream can't be created (missing directory, permissions) or getMessage().writeTo(os) fails (message content unreadable, disk full, stream closed).

Common situations: Target directory doesn't exist or is read-only, disk quota/full, illegal characters in filename on the OS, very large attachments exceeding disk space, message content corrupted on server.

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/f1f8fb4ec7eac914. Report an issue: GitHub.

Appendix: source

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

  /**
   * Export message content to a filename.
   *
   * @param filename
   *          the target filename
   * @param foldername
   *          the parent folder of filename
   * @throws KettleException
   */

  public void saveMessageContentToFile( String filename, String foldername ) throws KettleException {
    OutputStream os = null;
    try {
      os = KettleVFS.getInstance( bowl )
        .getOutputStream( foldername + ( foldername.endsWith( "/" ) ? "" : "/" ) + filename, false );
      getMessage().writeTo( os );
      updateSavedMessagesCounter();
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "MailConnection.Error.SavingMessageContent", ""
        + this.message.getMessageNumber(), filename, foldername ), e );
    } finally {
      if ( os != null ) {
        IOUtils.closeQuietly( os );
      }
    }
  }

  /**
   * Save attached files to a folder.
   *
   * @param foldername
   *          the target foldername
   * @throws KettleException
   */
  public void saveAttachedFiles( String foldername ) throws KettleException {
    saveAttachedFiles( foldername, null );
  }

View on GitHub (pinned to f3058517a1)