pentaho/pentaho-kettle · error · KettleException

LDAPOutput.Error.NewDNFieldMissing

LDAPOutput.Error.NewDNFieldMissing

Error message

LDAPOutput.Error.NewDNFieldMissing

What it means

LDAPOutput throws this when the transformation is in UPDATE/INSERT-or-UPDATE (rename DN) mode and the configured 'New DN field' name is empty after variable substitution. The step needs a stream field holding the new distinguished name to perform the rename, so it aborts processRow with a KettleException.

Solutions

  1. Open the LDAP Output step dialog and set the 'New DN field' to a field present in the incoming stream
  2. Define the variable used in the New DN field name (e.g. in kettle.properties or via Set Variables step) so substitution yields a non-empty value
  3. If renames are not intended, switch the step's operation to Insert or Update-only mode which does not require a New DN field

Example fix

// before (transformation XML snippet)
<new_dn_field/>
// after
<new_dn_field>newDn</new_dn_field>
Defensive patterns

Strategy: validation

Validate before calling

String newDnField = environmentSubstitute(meta.getNewDnFieldName());
if (Utils.isEmpty(newDnField)) {
  throw new KettleException("New DN field must be set for rename operations");
}

Try / catch

try { transform.processRow(meta, data); } catch (KettleException e) {
  if (e.getMessage().contains("NewDNFieldMissing")) { logError("Configure the New DN field in the LDAP Output step"); }
  throw e;
}

Prevention

When it happens

Trigger: Running the LDAP Output step with operation type that renames entries (Update or Upsert/rename) while meta.getNewDnFieldName() is unset or resolves to an empty string after environmentSubstitute.

Common situations: Step misconfigured in the GUI (New DN field dropdown left blank); a variable like ${NEW_DN_FIELD} used in the field name is not defined at runtime so it substitutes to empty; transformation copied between environments where the variable is missing.

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/c56315b42e2e81df. Report an issue: GitHub.

Appendix: source

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

        }
        fieldsToUpdateInStreaml = null;
        fieldsToUpdateAttributel = null;

        data.attributes = new String[data.nrfields];
        if ( meta.getOperationType() == LDAPOutputMeta.OPERATION_TYPE_UPSERT && data.nrfieldsToUpdate > 0 ) {
          data.attributesToUpdate = new String[data.nrfieldsToUpdate];
        }
      }

      if ( meta.getOperationType() == LDAPOutputMeta.OPERATION_TYPE_RENAME ) {
        String oldDnField = environmentSubstitute( meta.getOldDnFieldName() );
        if ( Utils.isEmpty( oldDnField ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.OldDNFieldMissing" ) );
        }

        String newDnField = environmentSubstitute( meta.getNewDnFieldName() );
        if ( Utils.isEmpty( newDnField ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "LDAPOutput.Error.NewDNFieldMissing" ) );
        }

        // return the index of the field in the input stream
        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 {

View on GitHub (pinned to f3058517a1)