spring-projects/spring-security · error · IllegalStateException

Embedded LDAP server is not provided

Error message

Embedded LDAP server is not provided

What it means

LdapAuthenticationProviderConfigurer's embedded-LDAP helper throws IllegalStateException('Embedded LDAP server is not provided') when no LDAP source is configured: no embedded server was started and no external context source/provider is available. It is a guard so that building fails fast with a clear message instead of a confusing downstream connection error.

Source

Thrown at config/src/main/java/org/springframework/security/config/annotation/authentication/configurers/ldap/LdapAuthenticationProviderConfigurer.java:583

				contextSource.setUserDn(this.managerDn);
				if (this.managerPassword == null) {
					throw new IllegalStateException("managerPassword is required if managerDn is supplied");
				}
				contextSource.setPassword(this.managerPassword);
			}
			contextSource = postProcess(contextSource);
			return contextSource;
		}

		private void startEmbeddedLdapServer() {
			if (unboundIdPresent) {
				UnboundIdContainer unboundIdContainer = new UnboundIdContainer(this.root, this.ldif);
				unboundIdContainer.setPort(getPort());
				postProcess(unboundIdContainer);
				this.port = unboundIdContainer.getPort();
			}
			else {
				throw new IllegalStateException("Embedded LDAP server is not provided");
			}
		}

		private int getPort() {
			if (this.port == null) {
				this.port = getDefaultPort();
			}
			return this.port;
		}

		private int getDefaultPort() {
			try (ServerSocket serverSocket = new ServerSocket(DEFAULT_PORT, 50, InetAddress.getLoopbackAddress())) {
				return serverSocket.getLocalPort();
			}
			catch (IOException ex) {
				return RANDOM_PORT;
			}
		}

View on GitHub (pinned to 96852e8860)

Solutions

  1. Add the embedded LDAP SDK dependency: com.unboundid:unboundid-ldapsdk, so the embedded server can start.
  2. Or configure an external server explicitly via .contextSource().url("ldap://host:389/dc=example,dc=com").
  3. If using a custom ContextSource, set it via contextSourceConfiguration so build() does not fall into the error branch.
  4. Verify the ldif/root settings only when embedding; otherwise provide the external URL.

Example fix

// before
auth.ldapAuthentication().userSearchFilter("(uid={0})"); // no LDAP source
// after
auth.ldapAuthentication().userSearchFilter("(uid={0})")
    .contextSource().url("ldap://ldap.example.com:389/dc=example,dc=com");
Defensive patterns

Strategy: validation

Validate before calling

// ensure an LDAP source exists before building
boolean hasExternal = ldapUrl != null && !ldapUrl.isBlank();
boolean hasEmbeddedSdk = ClassUtils.isPresent("com.unboundid.ldap.sdk.LDAPServer", getClass().getClassLoader());
if (!hasExternal && !hasEmbeddedSdk) {
    throw new IllegalStateException("Configure contextSource().url(...) or add unboundid-ldapsdk for embedded LDAP");
}

Try / catch

try {
    ldapAuth.build();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Embedded LDAP server")) {
        throw new ConfigurationException("No LDAP source configured: provide contextSource().url or embedded SDK", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Building the LDAP authentication config without calling contextSourceConfiguration().ldapCompare()/embedded server setup and without an external ContextSource — i.e. neither an embedded UnboundIdContainer can be created (e.g. UnboundID not on classpath) nor an external server provided.

Common situations: Using embedded LDAP without the unboundid-ldapsdk dependency so the embedded branch is skipped; forgetting to configure any LDAP source at all; custom build() paths where contextSource was never set.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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