{"record":{"id":"1ae75a4d0321e390","repo":"pentaho/pentaho-kettle","slug":"ldapconnection-error-insert","errorCode":"LDAPConnection.Error.Insert","errorMessage":"LDAPConnection.Error.Insert","messagePattern":"LDAPConnection\\.Error\\.Insert","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/ldap/impl/src/main/java/org/pentaho/di/trans/steps/ldapinput/LDAPConnection.java","lineNumber":369,"sourceCode":"   *          : Distinguished Name (Key for lookup)\n   * @param attributes\n   *          : contains all the attributes to set for insert\n   * @param values\n   *          : contains all the values for attributes\n   * @param multValuedSeparator\n   *          : multi-valued attributes separator\n   * @throws KettleException\n   */\n  public void insert( String dn, String[] attributes, String[] values, String multValuedSeparator ) throws KettleException {\n    try {\n\n      Attributes attrs = buildAttributes( dn, attributes, values, multValuedSeparator );\n      // We had all attributes\n      // Let's insert now\n      getInitialContext().createSubcontext( dn, attrs );\n\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"LDAPConnection.Error.Insert\", dn ), e );\n    }\n\n  }\n\n  /**\n   * 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\n   * otherwise, we will perform an update\n   *\n   * @param dn\n   *          : Distinguished Name (Key for lookup)\n   * @param attributes\n   *          : contains all the attributes to set for insert\n   * @param values\n   *          : contains all the values for attributes\n   * @param attributesToUpdate\n   *          : contains attributes to update\n   * @param valuesToUpdate\n   *          : contains values for attributes to update","sourceCodeStart":351,"sourceCodeEnd":387,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/ldap/impl/src/main/java/org/pentaho/di/trans/steps/ldapinput/LDAPConnection.java#L351-L387","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconnection.insert(dn, attrs, vals, \";\"); // fails on rerun\n// after\ntry {\n  connection.insert(dn, attrs, vals, \";\");\n} catch (KettleException e) {\n  connection.upsert(dn, attrs, vals, \";\"); // update if already present\n}","handlingStrategy":"validation","validationCode":"// Check for existing entry and parent OU before insert\nconnection.setSearchBase(dn);\nconnection.setFilter(\"(objectClass=*)\");\nconnection.search(); // non-empty => already exists; use upsert() instead","typeGuard":null,"tryCatchPattern":"try {\n  connection.insert(dn, attrs, vals, \";\");\n} catch (KettleException e) {\n  if (ExceptionUtils.getRootCause(e) instanceof NameAlreadyBoundException) {\n    connection.upsert(dn, attrs, vals, \";\"); // already exists -> update\n  } else { throw e; }\n}","preventionTips":["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"],"tags":["ldap","kettle","insert","jndi"],"backgroundTag":"file-already-exists","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}