pentaho/pentaho-kettle · error · KettleException

Mail.Log.AuthenticationUserFieldEmpty

Error message

Mail.Log.AuthenticationUserFieldEmpty

What it means

Thrown by Mail.validateMetaFields when SMTP authentication is set to basic (AUTENTICATION_BASIC) but meta.getAuthenticationUser() is empty. The Mail step requires a username whenever basic SMTP auth is enabled, so it aborts before sending. Password absence is checked next as a separate error (3196).

Solutions

1. Enter the SMTP username in the Mail step's Authentication User field.
2. Call meta.setAuthenticationUser("smtpUser") in code when using basic authentication.
3. If authentication is not required, change the authentication option to 'none' instead of leaving the user blank.
4. If the user comes from a ${variable}, confirm the variable is defined in kettle.properties or the launch environment.

Example fix

// before
meta.setUsingAuthentication(MailMeta.AUTENTICATION_BASIC);
// after
meta.setUsingAuthentication(MailMeta.AUTENTICATION_BASIC);
meta.setAuthenticationUser("smtpUser");
meta.setAuthenticationPassword("smtpPass");

if ( MailMeta.AUTENTICATION_BASIC.equals( meta.isUsingAuthentication() )
     && ( meta.getAuthenticationUser() == null || meta.getAuthenticationUser().trim().isEmpty() ) ) {
  throw new IllegalArgumentException("Mail step: authentication user required for basic auth");
}

try { transformation.execute(); } catch ( KettleException e ) { if ( e.getMessage().contains("AuthenticationUserFieldEmpty") ) { /* supply credentials or disable auth */ } else { throw e; } }

When it happens

Trigger: Enabling 'Use authentication' with the basic option in the Mail step and leaving the Authentication User field blank; code-built MailMeta setting authentication to basic without setAuthenticationUser(...); the username being supplied via a variable that resolves to empty.

Common situations: Shared transformations where credentials were stripped for security; users selecting basic auth intending OAuth/other and not filling user fields; environment variables for SMTP user not defined on the execution server.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Mail.Log.AuthenticationPasswordFieldEmpty
• Mail.Exception.CouldnotFindAuthenticationPassField
• Mail.Exception.CouldnotFindAuthenticationUserField
• Mail.Log.DestinationFieldEmpty
• Mail.Log.DynamicFilenameFieldEmpty

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

Appendix: source

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

    }

    // Check Attached filenames when dynamic
    if ( meta.isDynamicFilename() && Utils.isEmpty( meta.getDynamicFieldname() ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "Mail.Log.DynamicFilenameFieldEmpty" ) );
    }

    // Check Attached zipfilename when dynamic
    if ( meta.isZipFilenameDynamic() && Utils.isEmpty( meta.getDynamicZipFilenameField() ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "Mail.Log.DynamicZipFilenameFieldEmpty" ) );
    }

    validateZipFiles( meta );

    // check authentication
    if ( meta.isUsingAuthentication().equals( AUTENTICATION_BASIC ) ) {
      // check authentication user
      if ( Utils.isEmpty( meta.getAuthenticationUser() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "Mail.Log.AuthenticationUserFieldEmpty" ) );
      }

      // check authentication pass
      if ( Utils.isEmpty( meta.getAuthenticationPassword() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "Mail.Log.AuthenticationPasswordFieldEmpty" ) );
      }
    }
  }

  @VisibleForTesting
  void validateZipFiles( MailMeta meta ) throws KettleException {
    if ( meta.isZipFiles() && ( Utils.isEmpty( meta.getZipFilename() ) && !meta.isZipFilenameDynamic() ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "Mail.Log.ZipFilenameEmpty" ) );
    }
  }

  @VisibleForTesting
  void processAttachedFiles() throws KettleException {

View on GitHub (pinned to f3058517a1)