What causes "LDAPConnection.Error.Insert" in pentaho/pentaho-kettle?

Check e.getCause(): NameAlreadyBoundException means the entry exists — use upsert() or delete first.

pentaho/pentaho-kettle · error · KettleException

LDAPConnection.Error.Insert

LDAPConnection.Error.Insert

Error message

LDAPConnection.Error.Insert

What it means

LDAPConnection.insert(dn, attributes, values, multValuedSeparator) wraps any exception from createSubcontext(dn, attrs) in a KettleException with message key 'LDAPConnection.Error.Insert' (dn interpolated). The insert failed because the DN already exists (NameAlreadyBoundException), the parent DN is missing, the schema is violated, or permissions/connection problems — the JNDI cause is attached.

Solutions

Check e.getCause(): NameAlreadyBoundException means the entry exists — use upsert() or delete first.
Verify the parent OU exists and the DN suffix matches the directory's naming context.
Supply all MUST attributes required by the objectClass schema.
Grant the bind account create-child permission on the target OU.
Escape special characters in RDN values.

Example fix

// before
connection.insert(dn, attrs, vals, ";"); // fails on rerun
// after
try {
  connection.insert(dn, attrs, vals, ";");
} catch (KettleException e) {
  connection.upsert(dn, attrs, vals, ";"); // update if already present
}

Defensive patterns

Strategy: validation

Validate before calling

// Check for existing entry and parent OU before insert
connection.setSearchBase(dn);
connection.setFilter("(objectClass=*)");
connection.search(); // non-empty => already exists; use upsert() instead

Try / catch

try {
  connection.insert(dn, attrs, vals, ";");
} catch (KettleException e) {
  if (ExceptionUtils.getRootCause(e) instanceof NameAlreadyBoundException) {
    connection.upsert(dn, attrs, vals, ";"); // already exists -> update
  } else { throw e; }
}

Prevention

Make loads idempotent: check existence or use upsert() before insert
Validate all MUST attributes of the objectClass are provided
Confirm parent OUs exist before inserting children
Grant create-child permission to the bind account on the target OU

When it happens

Trigger: Inserting a DN that already exists in the directory; inserting under a parent OU that doesn't exist; attributes missing mandatory properties of the objectClass; bind user lacking create permission.

Common situations: Re-running a load transformation without clearing the directory first; wrong base DN so parent entries appear missing; unique attributes (uid, cn) colliding with existing entries; AD requiring sAMAccountName for user objects.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at plugins/ldap/impl/src/main/java/org/pentaho/di/trans/steps/ldapinput/LDAPConnection.java:369

   *          : Distinguished Name (Key for lookup)
   * @param attributes
   *          : contains all the attributes to set for insert
   * @param values
   *          : contains all the values for attributes
   * @param multValuedSeparator
   *          : multi-valued attributes separator
   * @throws KettleException
   */
  public void insert( String dn, String[] attributes, String[] values, String multValuedSeparator ) throws KettleException {
    try {

      Attributes attrs = buildAttributes( dn, attributes, values, multValuedSeparator );
      // We had all attributes
      // Let's insert now
      getInitialContext().createSubcontext( dn, attrs );

    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "LDAPConnection.Error.Insert", dn ), e );
    }

  }

  /**
   * Upsert record in LDAP First we will check if the entry exist based on DN If we can not find it, we will create it
   * otherwise, we will perform an update
   *
   * @param dn
   *          : Distinguished Name (Key for lookup)
   * @param attributes
   *          : contains all the attributes to set for insert
   * @param values
   *          : contains all the values for attributes
   * @param attributesToUpdate
   *          : contains attributes to update
   * @param valuesToUpdate
   *          : contains values for attributes to update

View on GitHub (pinned to f3058517a1)