pentaho/pentaho-kettle · error · KettleException

LDAPOutput.Error.DNFieldMissing

LDAPOutput.Error.DNFieldMissing

Error message

LDAPOutput.Error.DNFieldMissing

What it means

In non-rename mode (Insert/Update/Delete), the step requires a single 'DN field' containing the entry's distinguished name; when meta.getDnField() is empty after substitution it throws LDAPOutput.Error.DNFieldMissing.

Solutions

  1. Set the 'DN field' option in the LDAP Output dialog to a column from the incoming stream
  2. Define any variable used in the DN field name (kettle.properties or Set Variables)
  3. Verify the operation mode; rename mode uses Old/New DN fields instead, so configure those if renaming

Example fix

// before
<dn_field/>
// after
<dn_field>dn</dn_field>
Defensive patterns

Strategy: validation

Validate before calling

String dnField = environmentSubstitute(meta.getDnField());
if (Utils.isEmpty(dnField)) {
  throw new KettleException("DN field must be configured on LDAP Output");
}

Try / catch

try { step.processRow(); } catch (KettleException e) {
  if (e.getMessage().contains("DNFieldMissing")) { logError("Set the DN field in the LDAP Output dialog"); }
  throw e;
}

Prevention

When it happens

Trigger: LDAP Output in Insert, Update, or Delete mode with no DN field configured, or the DN field name resolves to empty via an undefined variable.

Common situations: Freshly added step never fully configured; transformation migrated between environments where the DN field variable is undefined; user switched modes and the DN field was cleared.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at plugins/ldap/impl/src/main/java/org/pentaho/di/trans/steps/ldapoutput/LDAPOutput.java:151

        data.indexOfOldDNField = getInputRowMeta().indexOfValue( oldDnField );

        if ( data.indexOfOldDNField < 0 ) {
          // the field is unreachable!
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.CanNotFindField", oldDnField ) );
        }
        // return the index of the field in the input stream
        data.indexOfNewDNField = getInputRowMeta().indexOfValue( newDnField );

        if ( data.indexOfNewDNField < 0 ) {
          // the field is unreachable!
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.CanNotFindField", newDnField ) );
        }

      } else {
        String dnField = environmentSubstitute( meta.getDnField() );
        // Check Dn field
        if ( Utils.isEmpty( dnField ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.DNFieldMissing" ) );
        }

        // return the index of the field in the input stream
        data.indexOfDNField = getInputRowMeta().indexOfValue( dnField );

        if ( data.indexOfDNField < 0 ) {
          // the field is unreachable!
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.CanNotFindField", dnField ) );
        }
      }

    }

    incrementLinesInput();
    String dn = null;

    try {
      if ( meta.getOperationType() != LDAPOutputMeta.OPERATION_TYPE_RENAME ) {

View on GitHub (pinned to f3058517a1)