LDAP Error Codes

Understanding LDAP error codes—formally called result codes—is essential for anyone integrating with or troubleshooting LDAP directory services. These codes provide the definitive outcome of every LDAP operation, conveying both successes and failures in a standardized protocol-defined format. Decoding them quickly and accurately can make the difference between hours of guesswork and a rapid resolution of directory authentication, search, or integration issues.

This guide demystifies LDAP error/result codes, distinguishes their meanings, navigates common implementation nuances (including Active Directory subcodes), and equips you with effective troubleshooting strategies grounded in standards and real-world behavior.

What Are LDAP Error Codes?

In the LDAP protocol, every operation (search, bind, modify, etc.) results in exactly one result code returned from the server to the client. These codes are numeric values, each with a symbolic name (e.g., LDAP_SUCCESS, LDAP_INVALID_CREDENTIALS), that indicate the specific outcome of the request.

LDAP result codes are defined in RFC 4511, with additional codes introduced by some vendors or as part of protocol extensions. Importantly, not every code indicates an error—some specify success or an alternative (but non-fatal) result, such as a referral or a 'false' result from a compare operation.

For example:

• success (0): Operation was successful.
• compareFalse (5) / compareTrue (6): Result of an LDAP compare operation (not errors).
• referral (10): Server indicates the operation should be retried on another server.
• saslBindInProgress (14): Client should continue multi-step SASL authentication.

Most other codes, however, indicate various error conditions, protocol problems, or constraint violations. Correctly identifying whether a code signals an error, or simply a completed protocol step, is vital for robust LDAP integration and troubleshooting.

LDAP Result Code Reference Table

The following table summarizes the core LDAP result codes as specified in RFC 4511, mapping their numeric values, symbolic names, and canonical descriptions. This set is supported by all standards-compliant LDAP implementations.

This table distinguishes genuinely non-error codes (success, compareFalse, compareTrue, referral, saslBindInProgress) from error codes you must handle explicitly. For a complete listing with further explanations, consult authoritative references.

How to Troubleshoot LDAP Error Codes

The meaning of an LDAP result code is always contextual—derived from the operation performed and the server's response. Effective troubleshooting begins by mapping the code to its scenario and then gathering supporting evidence (such as the LDAP Distinguished Name, search parameters, and server logs).

Troubleshooting Guide for Common Codes:

Code 49: invalidCredentials

Context: Authentication (bind) failed.

Common causes:

• The supplied DN or username does not exist.
• The password is incorrect.
• The user account is locked, disabled, or expired (especially with vendor subcodes).
• Account policy violation.

Example Workflow:

• Review the bind request: Which DN or username was supplied?
• Confirm the credentials independently (e.g., try another client).
• Inspect server logs for subcodes or accompanying messages (especially in Active Directory).
• If using Active Directory, check for extended diagnostics (see next section).

Code 32: noSuchObject

Context: Operation refers to a DN that does not exist.

Common causes:

• Typo or missing base DN in search or modify operation.
• Attempting to bind or operate on a deleted entry.
• Incorrect configuration of directory suffix.

Example Workflow:

• Double-check the DN provided—ensure case, spacing, and hierarchy match the directory.
• If searching, test with a broader or root DN.
• Review server logs for the exact DN the server reports as missing.

Other critical codes (like insufficientAccessRights (50), unwillingToPerform (53), or sizeLimitExceeded (4)) should be interpreted in operation context and may indicate permission issues, unsupported operations, or configuration/policy limits on the server.

Special Cases: Active Directory and Vendor-Specific Codes

Most LDAP servers implement RFC 4511 codes as specified. However, vendors commonly introduce additional diagnostic features or subcodes—especially to clarify authentication failures.

Active Directory Error 49 Subcodes

Active Directory always returns code 49 when authentication fails but adds a suberror code in the diagnostic message. This subcode pinpoints the specific reason for failure, such as expired passwords, account lockouts, or logon restrictions. These subcodes appear in the diagnostic message or server logs but are not standardized in the LDAP protocol itself.

Examples (illustrative; consult official AD documentation):

• 49.52e: Password expired
• 49.775: Account locked
• 49.530: Not permitted to logon at this time

Always retrieve the diagnostic message and refer to up-to-date vendor documentation to translate these subcodes into actionable remediation steps. For other vendors, consult the server’s documentation for any product-specific result codes or extensions.

Mapping LDAP Error Codes to Application Exceptions

How error/result codes surface in your application depends on the LDAP client library and the environment language:

• Java (JNDI): LDAP result codes are mapped to subclasses of NamingException (e.g., AuthenticationException for code 49, NameNotFoundException for code 32).
• .NET, Python, others: Each library defines its own mapping, often reflecting the major RFC 4511 result codes.

Understanding these mappings helps interpret stack traces or exception hierarchies and trace them to the underlying LDAP protocol response.

Common Misconceptions and Key Nuances

• Not every non-zero code is an error: Codes like compareFalse and referral denote valid, non-error outcomes. Always check the code's intended meaning in RFC 4511 or your server’s documentation.
• Code 49 is not 'wrong password' by default: Especially in Active Directory and similar implementations, code 49 means authentication failed for any reason—including password expiry, lockout, or policy enforcement—not only an incorrect password. Subcodes provide vital clarification.
• Result code meanings are not identical on all servers: While RFC 4511 is normative, major vendors (e.g., Microsoft, Novell) may document product-specific codes, extensions, or interpretations. Always check your directory’s official resources.
• RFC 4511 does not cover all codes: Some extension or control operations require or define additional error codes, registered per RFC 4521. When in doubt, look for extension documentation.

Further Reference and Official Documentation

For the most reliable and current LDAP result code definitions and troubleshooting information, consult:

• RFC 4511: “Lightweight Directory Access Protocol (LDAP): The Protocol” — the canonical protocol and result code definitions.
• OpenLDAP Administrator’s Guide: Dedicated appendix for result codes and extended explanations.
• Product-specific documentation for extension codes, vendor diagnostics, and subcodes (especially Active Directory or other LDAP server vendors).
• Official client library documentation for your programming environment’s LDAP binding or API.

Mastery of LDAP result codes and their operational context equips you to debug, integrate, and operate directory-connected systems with clarity and efficiency.

Sources

• www.rfc-editor.org — rfc4511
• www.openldap.org — appendix-ldap-result-codes.html
• www.openldap.org — appendix-common-errors.html
• my.eng.utah.edu — jndi-ldap-gl.html
• datatracker.ietf.org — rfc4521