pentaho/pentaho-kettle · error · KettleException

Mail.Exception.CouldnotFindDestinationField

Error message

Mail.Exception.CouldnotFindDestinationField

What it means

Thrown by cacheFieldsPosition when the destination (To) field configured in the Mail meta cannot be found in the incoming row's RowMeta. The step needs the recipient address to come from a field in the stream, and indexOfValue returned -1. This fails fast before any mail is sent.

Solutions

1. Check the 'Destination fieldname' in the Mail step settings matches an existing incoming column exactly (case-sensitive)
2. Add a Select Values / Add constants step upstream to guarantee the field exists
3. Open the step and re-pick the field from the dropdown after changing upstream metadata

Example fix

// before
meta.setDestination("dest_adress");
// after (matches actual upstream field)
meta.setDestination("dest_address");

// before the Mail step, verify the field exists
if (rowMeta.indexOfValue("dest_address") < 0) {
  throw new KettleValueException("Field dest_address missing from input stream");
}

try {
  step.processRow();
} catch (KettleException e) {
  if (e.getMessage().contains("CouldnotFindDestinationField")) {
    logError("Fix the Destination fieldname in the Mail step: " + e.getMessage());
  }
}

When it happens

Trigger: processRow calls cacheFieldsPosition; meta.getDestination() names a field that does not exist in previousRowMeta, so data.indexOfDestination stays -1 after indexOfValue.

Common situations: Typo in the destination field name; upstream step renamed or dropped the column; field only appears conditionally upstream; transformation modified after the Mail step was configured.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Mail.Exception.CouldnotFindContactPersonField
• Mail.Exception.CouldnotFindContactPhoneField
• Mail.Exception.CouldnotFindDestinationBCcField
• Mail.Exception.CouldnotFindDestinationCcField
• Mail.Exception.CouldnotFindReplyAddressField

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

Appendix: source

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

        logError( BaseMessages.getString( PKG, "Mail.Error.AddingImage", e.getMessage() ) );
      } finally {
        if ( image != null ) {
          try {
            image.close();
          } catch ( Exception e ) { /* Ignore */
          }
        }
      }
    }
  }

  private void cacheFieldsPosition( MailMeta meta, MailData data ) throws KettleException {
    // cache the position of the destination field
    if ( data.indexOfDestination < 0 ) {
      String realDestinationFieldName = meta.getDestination();
      data.indexOfDestination = data.previousRowMeta.indexOfValue( realDestinationFieldName );
      if ( data.indexOfDestination < 0 ) {
        throw new KettleException( BaseMessages.getString(
          PKG, "Mail.Exception.CouldnotFindDestinationField", realDestinationFieldName ) );
      }
    }

    // Cc
    if ( !Utils.isEmpty( meta.getDestinationCc() ) ) {
      // cache the position of the Cc field
      if ( data.indexOfDestinationCc < 0 ) {
        String realDestinationCcFieldname = meta.getDestinationCc();
        data.indexOfDestinationCc = data.previousRowMeta.indexOfValue( realDestinationCcFieldname );
        if ( data.indexOfDestinationCc < 0 ) {
          throw new KettleException( BaseMessages.getString(
            PKG, "Mail.Exception.CouldnotFindDestinationCcField", realDestinationCcFieldname ) );
        }
      }
    }
    // BCc
    if ( !Utils.isEmpty( meta.getDestinationBCc() ) ) {

View on GitHub (pinned to f3058517a1)