Troubleshooting

This guide helps users understand and resolve common LDAP (Lightweight Directory Access Protocol) connection or authentication errors encountered when integrating with Active Directory (AD) or other directory services. Each section provides a simplified, Message error message, its meaning, possible causes, and clear remediation steps.

1) Authentication expired / must change password

Message: “Your password or account has expired.”

Technical details (examples):

• AcceptSecurityContext error, data 532
• ACCOUNT_EXPIRED / PASSWORD_EXPIRED

Code(s): 532, 701, 773

Meaning: AD requires a password reset or the account has passed its expiry.

What You Can Do:

1. Reset your password through your organisation’s password portal.
2. Contact your IT administrator to renew your account.
3. Check if your account needs reactivation.

---

2) Account locked

Message: “Your account has been locked.”

Technical details (examples):

• data 775
• “locked out”, ACCOUNT_LOCKED

Code(s): 775

Meaning: Too many failed attempts or a policy lock.

What You Can Do:

1. Wait for the automatic unlock period (usually 15–30 minutes).
2. Contact your IT administrator to unlock your account immediately.
3. Ensure you are using the correct password to avoid further lockouts.

---

3) Invalid credentials / Bind DN issues

Message: “Invalid Admin DN/Bind DN or password. Please verify your LDAP credentials and try again.”

Technical details (examples):

• LdapErr: ... data 52e ...
• LDAP result code 49
• “user not found” patterns (e.g., 525)

Code(s): 52e, 525, 49

Meaning: The Bind DN (username) or password is wrong, or the account is unusable.

What You Can Do:

1. Confirm the correct username and password by logging into AD.
2. Try alternate username formats (e.g., [email protected] or DOMAIN\user).
3. Check if the account is active, not locked, and has a non-expired password.
4. Verify the bind DN format matches your directory structure.

---

4) Referral (cross-domain)

Message: “The directory server redirected your request. Please check the Base DN or domain configuration.”

Technical details (examples):

• 0000202B: RefErr ...
• data 0, 1 access points ...
• Contains “referral”

Code(s): 202B, 10

Meaning: The query targets data in another domain / partition.

What You Can Do:

1. Update your Base DN to the correct domain (e.g., DC=company,DC=com).
2. Use Global Catalog ports 3268 (LDAP) or 3269 (LDAPS) for cross-domain queries.
3. Verify DNS and trust configurations between domains.
4. Ensure your bind DN has access to the target domain.

---

5) Stronger authentication required

Message: “The server requires stronger authentication. TLS/SSL is required for this operation.”

Technical details (examples):

• StrongerAuthRequired
• STRONG_AUTH_REQUIRED

Code(s): 8

Meaning: The server enforces signing, sealing, channel binding, or LDAPS.

What You Can Do:

1. Use LDAPS (636) instead of plain LDAP (389).
2. Enable channel binding if required by your server.
3. Verify that TLS/SSL certificates are properly configured.
4. Check if the server requires signed or sealed connections.

---

6) Certificate validation failed

Message: “SSL/TLS certificate validation failed. The server certificate is not trusted.”

Technical details (examples):

• “self signed certificate”
• “unable to verify”
• Mentions of CERT_ or “certificate”

Code(s): (none)

Meaning: The server certificate is invalid, expired, mismatched, or untrusted.

What You Can Do:

1. Upload the correct SSL certificate for your LDAP server.
2. Verify the certificate is valid and not expired.
3. Ensure the certificate hostname matches your server URL.
4. Check if you need to add intermediate CA certificates.

---

7) Server unavailable / DC unreachable

Message: “The directory server is currently unavailable or unreachable.”

Technical details (examples):

• SERVER_DOWN
• UNAVAILABLE

Code(s): 81

Meaning: The client can’t reach the DC or the service isn’t responding.

What You Can Do:

1. Verify the server is running and accessible on the network.
2. Check if firewall rules are blocking LDAP ports (389, 636, 3268, 3269).
3. Confirm the server hostname or IP address is correct.
4. Try again later in case of transient server issues.

---

8) DNS hostname not found

Message: “Unable to connect to the directory server. The hostname could not be found.”

Technical details (examples):

• getaddrinfo ENOTFOUND <host>
• Error .code === 'ENOTFOUND'

Code(s): ENOTFOUND

Meaning: DNS cannot resolve the LDAP hostname.

What You Can Do:

1. Verify the LDAP hostname is correct and properly spelled.
2. Use a Fully Qualified Domain Name (FQDN) instead of a short name.
3. Ensure your system can resolve the domain name (check DNS settings).
4. Try using the server IP address temporarily to test connectivity.

---

9) Connection reset (TLS/port mismatch)

Message: “Connection to the directory server was unexpectedly closed. Please check your encryption settings.”

Technical details (examples):

• read ECONNRESET
• Error .code === 'ECONNRESET'

Code(s): ECONNRESET

Meaning: The server closed the socket, often due to protocol/port mismatch or TLS issues.

What You Can Do:

1. Use the correct port: 389 for LDAP, 636 for LDAPS.
2. Verify the server’s SSL certificate is valid and trusted.
3. Ensure your system supports TLS 1.2 or later.
4. Check if LDAP signing or channel binding is correctly configured.
5. Verify you are not mixing LDAP/LDAPS protocols and ports.

---

10) Invalid or non-existent DN / Base DN

Message: “The specified Base DN does not exist or has invalid syntax.”

Technical details (examples):

• NO_SUCH_OBJECT
• INVALID_DN_SYNTAX
• Related protocol errors

Code(s): 32, 34

Meaning: The Base DN is wrong or malformed, or the target object doesn’t exist.

What You Can Do:

1. Verify the Base DN matches your directory structure (e.g., DC=company,DC=com).
2. Check for typos in the DN components.
3. Ensure the DN format follows LDAP standards (comma-separated, no spaces around commas).
4. Confirm the organisational unit or domain exists in your directory.

---

11) Query limits exceeded (time/size/admin)

Message (varies by limit):

• Time limit: “The search operation took too long and timed out.”
• Size limit: “The search returned too many results and hit the size limit.”
• Admin limit: “An administrative limit was exceeded on the server.”

Technical details (examples):

• Time limit exceeded / size limit exceeded / admin limit exceeded

Code(s): 3 (time), 4 (size), 11 (admin)

What You Can Do (for all):

• Refine your search filter to return fewer results.
• Use pagination for large result sets.

Additionally:

• Time limit (3): Increase the time limit in your configuration.
• Size limit (4): Increase the size limit in your configuration.
• Admin limit (11): Contact your LDAP administrator to adjust server limits.

---

12) Insufficient access / unwilling to perform

Message (varies):

• “Insufficient access rights to perform this operation.”
• or “The server is unwilling to perform the requested operation.”

Technical details (examples):

• Insufficient access errors
• Unwilling to perform responses

Code(s): 50 (insufficient access), 53 (unwilling to perform)

Meaning: Permissions/policies block the operation.

What You Can Do:

1. Verify your bind credentials have the necessary permissions.
2. Check if the account has read/write access to the target DN.
3. Ensure the operation is allowed by server policies.
4. Contact your LDAP administrator to grant appropriate permissions.

---

13) Unknown / generic failure

Message: Connection failed: <technical error message>

Meaning: The error didn’t match a known category.

What You Can Do:

1. Verify all connection parameters are correct.
2. Check the technical error details below.
3. Review LDAP server logs for more information.
4. Contact your AD administrator if the issue persists.

---

Summary Table

---

Best Practices for Stable LDAP Connectivity

• Verify hostname, port, and encryption settings (LDAP 389 vs LDAPS 636; Global Catalog 3268/3269).
• Prefer LDAPS (636) and correct TLS certificates (validity, hostname, intermediates).
• Ensure the Bind DN format matches your directory structure and that the account is active (not expired/locked).

Getting Support:

When contacting Zluri support, always include:

• Logs: Go to: C:\Users\Administrator\AppData\Roaming\zluri-ldap-connecter\logs and share the log file.
• Error Information: Complete error response and HTTP status code
• Timeline: When the error occurred.
• Agent Name

Limitations

• Retry Action not available: If an LDAP action fails due to a callback issue, the “Retry” button isn’t supported at the moment.
• One LDAP action per workflow: Each workflow can currently include only one LDAP-related action. This is because LDAP sync operations run asynchronously — Zluri must first complete validation and sync user data before performing another LDAP step. Adding multiple LDAP actions in a single workflow could cause data conflicts or timing issues.