What causes " " in spring-projects/spring-security?

Verify the LDAP server is reachable: test with ldapsearch or telnet to host:port from the app host.

spring-projects/spring-security · error · UncategorizedLdapException

<namingException.getMessage()>

Error message

<namingException.getMessage()>

What it means

During LDAP bind authentication, a javax.naming.NamingException occurred while binding the user's DN. BindAuthenticator wraps it via LdapUtils.convertLdapException(ex) and rethrows it as a Spring Security LDAP runtime exception (org.springframework.ldap.CommunicationException / AuthenticationException etc., whose message is the original naming exception's message). This surfaces low-level directory errors (connection refused, DNS failure, invalid DN) to callers of authenticate().

Source

Thrown at ldap/src/main/java/org/springframework/security/ldap/authentication/BindAuthenticator.java:135

			if (attrs == null || attrs.size() == 0) {
				attrs = ctx.getAttributes(userDn, getUserAttributes());
			}
			DirContextAdapter result = new DirContextAdapter(attrs, userDn, ctxSource.getBaseLdapName());
			if (ppolicy != null) {
				result.setAttributeValue(ppolicy.getID(), ppolicy);
			}
			logger.debug(LogMessage.format("Bound %s", fullDn));
			return result;
		}
		catch (NamingException ex) {
			// This will be thrown if an invalid user name is used and the method may
			// be called multiple times to try different names, so we trap the exception
			// unless a subclass wishes to implement more specialized behaviour.
			handleIfBindException(userDnStr, username, ex);
		}
		catch (javax.naming.NamingException ex) {
			if (!this.alsoHandleJavaxNamingBindExceptions) {
				throw LdapUtils.convertLdapException(ex);
			}
			handleIfBindException(userDnStr, username, LdapUtils.convertLdapException(ex));
		}
		finally {
			LdapUtils.closeContext(ctx);
		}
		return null;
	}

	private void handleIfBindException(String dn, String username, org.springframework.ldap.NamingException naming) {
		if ((naming instanceof org.springframework.ldap.AuthenticationException)
				|| (naming instanceof org.springframework.ldap.OperationNotSupportedException)) {
			handleBindException(dn, username, naming);
		}
		else {
			throw naming;
		}
	}

View on GitHub (pinned to 96852e8860)

Solutions

Verify the LDAP server is reachable: test with ldapsearch or telnet to host:port from the app host.
Check the context source URL/port/base DN configuration (e.g. DefaultSpringSecurityContextSource) for typos.
Inspect the converted exception's message/cause to identify the underlying JNDI error code (e.g. communication vs name-not-found).
If user DNs are wrong, fix userSearchFilter/userDnPatterns so binds target valid entries.

Example fix

// before: vague bind failure with raw JNDI message
auth.ldapAuthentication().userDnPatterns("uid={0},ou=people")
  .contextSource().url("ldaps://ldap.example.com:389");
// after: correct scheme/port and reachable server
auth.ldapAuthentication().userDnPatterns("uid={0},ou=people")
  .contextSource().url("ldap://ldap.example.com:389");

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight LDAP reachability
try (LdapContext ctx = contextSource.getContext("", "")) {
    // server reachable and manager bind works
} catch (Exception e) {
    fail("LDAP unavailable: " + e.getMessage());
}

Try / catch

try {
    authProvider.authenticate(token);
} catch (org.springframework.ldap.CommunicationException e) {
    // directory unreachable — alert ops, show 'service unavailable'
} catch (AuthenticationException e) {
    // bad credentials path
}

Prevention

Add a startup health check that opens an anonymous/manager LDAP context.
Store LDAP URLs/ports in externalized, validated configuration.
Monitor JNDI error codes and alert on communication failures.
Use userSearch instead of raw DN patterns when DNs vary.

When it happens

Trigger: Calling BindAuthenticator.authenticate() (directly or via LdapAuthenticationProvider) when the LDAP bind operation throws a NamingException that is not an AuthenticationException, or when alsoHandleJavaxNamingBindExceptions is false so bind exceptions are not swallowed for retry with alternative DNs.

Common situations: LDAP server down or unreachable (network/firewall), wrong port or URL in the context source, malformed user DN patterns, TLS/SSL handshake problems, or directory service failures (e.g. referral errors) during login.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/2f9eb2f3a42b0d7d. Report an issue: GitHub.