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

Check the 'Authentication user' field name in the Mail step against the actual input row fields.

pentaho/pentaho-kettle · error · KettleException

Mail.Exception.CouldnotFindAuthenticationUserField

Error message

Mail.Exception.CouldnotFindAuthenticationUserField

What it means

The Mail step is configured for BASIC or OAUTH authentication and needs the authentication user name from a field in the incoming row, but no field matching meta.getAuthenticationUser() exists in the row metadata. The lookup in cacheFieldsPosition returns -1 and this KettleException is thrown.

Solutions

Check the 'Authentication user' field name in the Mail step against the actual input row fields.
Preview the incoming hop to confirm the user field reaches this step.
If the username is constant, use the static user setting rather than a field reference.

Example fix

// before
// Authentication user field: "usr" but stream contains "username"
// after
// Set the Authentication user field to "username" (exact match of the stream field)

Defensive patterns

Strategy: validation

Validate before calling

if ((meta.isUsingAuthentication().equals(MailMeta.AUTENTICATION_BASIC)
    || meta.isUsingAuthentication().equals(MailMeta.AUTENTICATION_OAUTH))
    && rowMeta.indexOfValue(meta.getAuthenticationUser()) < 0) {
  throw new KettleException("Auth user field not found: " + meta.getAuthenticationUser());
}

Try / catch

try { sendMail(); } catch (KettleException e) { if (e.getMessage().contains("CouldnotFindAuthenticationUserField")) { logError("Verify the authentication user field name in the Mail step"); } throw e; }

Prevention

Select the user field from the dropdown in the step dialog rather than typing it.
Include an explicit field check upstream when the transformation schema can change.
Keep authentication fields stable across transformation refactors.

When it happens

Trigger: Authentication mode is 'Basic' or 'OAuth', and data.previousRowMeta.indexOfValue(realAuthenticationUser) < 0 because the configured user field name does not exist in the input stream.

Common situations: User field name typo; upstream step deleted/renamed the field; step copied from another transformation where the input schema differed.

Understand the failure class

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

Related errors

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

Appendix: source

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

    // Authentication
    if ( meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_BASIC ) ) {
      // cache the position of the Authentication password field
      if ( data.indexOfAuthenticationPass < 0 ) {
        String realAuthenticationPassword = Utils.resolvePassword( variables, meta.getAuthenticationPassword() );
        data.indexOfAuthenticationPass = data.previousRowMeta.indexOfValue( realAuthenticationPassword );
        if ( data.indexOfAuthenticationPass < 0 ) {
          throw new KettleException( BaseMessages.getString(
            PKG, "Mail.Exception.CouldnotFindAuthenticationPassField", realAuthenticationPassword ) );
        }
      }
    }
    // cache the position of the Authentication user field
    if ( meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_BASIC ) || meta.isUsingAuthentication().equals( MailMeta.AUTENTICATION_OAUTH ) ) {
      if ( data.indexOfAuthenticationUser < 0 ) {
        String realAuthenticationUser = meta.getAuthenticationUser();
        data.indexOfAuthenticationUser = data.previousRowMeta.indexOfValue( realAuthenticationUser );
        if ( data.indexOfAuthenticationUser < 0 ) {
          throw new KettleException( BaseMessages.getString(
            PKG, "Mail.Exception.CouldnotFindAuthenticationUserField", realAuthenticationUser ) );
        }
      }
    }
    // Mail Subject
    if ( !Utils.isEmpty( meta.getSubject() ) ) {
      // cache the position of the subject field
      if ( data.indexOfSubject < 0 ) {
        String realSubject = meta.getSubject();
        data.indexOfSubject = data.previousRowMeta.indexOfValue( realSubject );
        if ( data.indexOfSubject < 0 ) {
          throw new KettleException( BaseMessages.getString(
            PKG, "Mail.Exception.CouldnotFindSubjectField", realSubject ) );
        }
      }
    }
    // Mail Comment
    if ( !Utils.isEmpty( meta.getComment() ) ) {

View on GitHub (pinned to f3058517a1)