spring-projects/spring-security · error · NamingException

Failed to obtain DirContext

Error message

Failed to obtain DirContext

What it means

KerberosLdapContextSource.getDirContextInstance collects any exception thrown while creating the LDAP DirContext and rethrows it; if creation fails silently and no context is produced, it throws this NamingException. It means the library could not establish an LDAP directory context (typically the Active Directory/LDAP server the Kerberos setup points at).

Source

Thrown at kerberos/kerberos-client/src/main/java/org/springframework/security/kerberos/client/ldap/KerberosLdapContextSource.java:131

		DirContext dirContext = Subject.doAs(serviceSubject, new PrivilegedAction<@Nullable DirContext>() {

			@Override
			public @Nullable DirContext run() {
				try {
					return KerberosLdapContextSource.super.getDirContextInstance(environment);
				}
				catch (NamingException ex) {
					suppressedException[0] = ex;
					return null;
				}
			}
		});

		if (suppressedException[0] != null) {
			throw suppressedException[0];
		}
		if (dirContext == null) {
			throw new NamingException("Failed to obtain DirContext");
		}

		return dirContext;
	}

	/**
	 * The login configuration to get the serviceSubject from LoginContext.
	 * @param loginConfig the login config
	 */
	public void setLoginConfig(Configuration loginConfig) {
		this.loginConfig = loginConfig;
	}

	private Subject login() throws AuthenticationException {
		try {
			LoginContext lc = new LoginContext(KerberosLdapContextSource.class.getSimpleName(), null, null,
					this.loginConfig);

View on GitHub (pinned to 96852e8860)

Solutions

  1. Verify the LDAP URL(s) are reachable from the app host (e.g. `nc -vz ldap://dc.example.com 389`).
  2. Check the baseEnvironmentProperties and authentication credentials/SPN configured on the context source.
  3. Confirm DNS resolves the AD domain controller and searchBase is correct.
  4. Inspect the suppressed exception logged by the context creation to find the root cause (connect/auth failure).
  5. If using ldaps, ensure the CA certificate is in the truststore.

Example fix

// before
KerberosLdapContextSource ctx = new KerberosLdapContextSource();
ctx.setUrls("ldap://wrong-host:389");
// after
KerberosLdapContextSource ctx = new KerberosLdapContextSource();
ctx.setUrls("ldap://dc1.example.com:389");
ctx.setSearchBase("dc=example,dc=com");
ctx.afterPropertiesSet();
Defensive patterns

Strategy: validation

Validate before calling

if (ctx.getUrls() == null || ctx.getUrls().isEmpty()) throw new IllegalStateException("LDAP urls not configured");
// verify reachability first
try (Socket s = new Socket(host, port)) { /* reachable */ } catch (IOException e) { /* fail fast */ }

Try / catch

try {
  DirContext dc = kerberosLdapContextSource.getDirContextInstance(...);
} catch (NamingException e) {
  LOG.error("LDAP context creation failed; check LDAP URL/credentials/DNS", e);
  throw new AuthenticationServiceException("Directory unavailable", e);
}

Prevention

When it happens

Trigger: Calling getDirContextInstance when the underlying context factory returns null after a suppressed failure — e.g. unreachable LDAP URL, failed SPN/service-account authentication, or DNS resolution failure for the domain controller.

Common situations: Spring Security Kerberos clients wiring KerberosLdapContextSource as the UserDetailsService: wrong ldapUrls, domain not resolvable, firewall blocking port 389/636, or misconfigured service account credentials.

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/f93f028d44a93a27. Report an issue: GitHub.