What causes "Mail.Exception.AttachedContentFileNameFieldEmpty" in pentaho/pentaho-kettle?

Set the 'Content filename field' (or equivalent attachment filename field) to a field from the input stream that holds the attachment file name.

pentaho/pentaho-kettle · error · KettleException

Mail.Exception.AttachedContentFileNameFieldEmpty

Error message

Mail.Exception.AttachedContentFileNameFieldEmpty

What it means

'Attach content from field' is enabled and the attached-content field resolved fine, but the 'attached content filename field' setting is empty. The step requires a filename to give the in-memory attachment a name, so it throws this KettleException.

Solutions

Set the 'Content filename field' (or equivalent attachment filename field) to a field from the input stream that holds the attachment file name.
Add an upstream step generating the filename field if it does not exist.
Disable 'Attach content from field' if you attach physical files instead.

Example fix

// before
// attachContentFileNameField = ""
// after
// meta.setAttachContentFileNameField("attachment_name"); // field produced upstream

Defensive patterns

Strategy: validation

Validate before calling

if (meta.isAttachContentFromField()
    && (meta.getAttachContentFileNameField() == null || meta.getAttachContentFileNameField().isEmpty())) {
  throw new KettleException("'Attach content from field' is enabled but the content filename field is empty");
}

Try / catch

try { sendMail(); } catch (KettleException e) { if (e.getMessage().contains("AttachedContentFileNameFieldEmpty")) { logError("Set the attachment content filename field in the Mail step"); } throw e; }

Prevention

Always pair the content field with a filename field when attaching from row data.
Run a metadata validation pass over transformations before scheduling them.
Document that content attachments require both fields to be configured.

When it happens

Trigger: meta.isAttachContentFromField() is true and Utils.isEmpty(meta.getAttachContentFileNameField()) — the filename field in the attachment settings was not specified.

Common situations: Configuring content attachment but overlooking the companion filename field; imported transformation metadata missing the filename setting.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at plugins/mail/impl/src/main/java/org/pentaho/di/trans/steps/mail/Mail.java:424

    if ( meta.isAttachContentFromField() ) {
      // We are dealing with file content directly loaded from file
      // and not physical file
      String attachedContentField = meta.getAttachContentField();
      if ( Utils.isEmpty( attachedContentField ) ) {
        // Empty Field
        throw new KettleException( BaseMessages.getString( PKG, "Mail.Exception.AttachedContentFieldEmpty" ) );
      }
      data.indexOfAttachedContent = data.previousRowMeta.indexOfValue( attachedContentField );
      if ( data.indexOfAttachedContent < 0 ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "Mail.Exception.CouldnotFindAttachedContentField", attachedContentField ) );
      }
      // Attached content filename
      String attachedContentFileNameField = meta.getAttachContentFileNameField();
      if ( Utils.isEmpty( attachedContentFileNameField ) ) {
        // Empty Field
        throw new KettleException( BaseMessages.getString(
          PKG, "Mail.Exception.AttachedContentFileNameFieldEmpty" ) );
      }
      data.IndexOfAttachedFilename = data.previousRowMeta.indexOfValue( attachedContentFileNameField );
      if ( data.IndexOfAttachedFilename < 0 ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "Mail.Exception.CouldnotFindAttachedContentFileNameField", attachedContentFileNameField ) );
      }
    } else {

      // Dynamic Zipfilename
      if ( meta.isZipFilenameDynamic() ) {
        // cache the position of the attached source filename field
        if ( data.indexOfDynamicZipFilename < 0 ) {
          String realZipFilename = meta.getDynamicZipFilenameField();
          data.indexOfDynamicZipFilename = data.previousRowMeta.indexOfValue( realZipFilename );
          if ( data.indexOfDynamicZipFilename < 0 ) {
            throw new KettleException( BaseMessages.getString(
              PKG, "Mail.Exception.CouldnotSourceAttachedZipFilenameField", realZipFilename ) );

View on GitHub (pinned to f3058517a1)