spring-projects/spring-security · error · IllegalStateException

Embedded LDAP server is not provided

Error message

Embedded LDAP server is not provided

What it means

EmbeddedLdapServerContextSourceFactoryBean.getObject() builds the embedded LDAP context source, but first checks the unboundIdPresent flag. Since the embedded server relies on UnboundID's SDK, absence of that library means no embedded server can be created and an IllegalStateException is thrown.

Source

Thrown at config/src/main/java/org/springframework/security/config/ldap/EmbeddedLdapServerContextSourceFactoryBean.java:131

	 * authenticate to a LDAP server.
	 */
	public void setManagerDn(String managerDn) {
		this.managerDn = managerDn;
	}

	/**
	 * The password for the manager DN. This is required if the
	 * {@link #setManagerDn(String)} is specified.
	 * @param managerPassword password for the manager DN
	 */
	public void setManagerPassword(String managerPassword) {
		this.managerPassword = managerPassword;
	}

	@Override
	public DefaultSpringSecurityContextSource getObject() throws Exception {
		if (!unboundIdPresent) {
			throw new IllegalStateException("Embedded LDAP server is not provided");
		}
		this.container = getContainer();
		this.port = this.container.getPort();
		DefaultSpringSecurityContextSource contextSourceFromProviderUrl = new DefaultSpringSecurityContextSource(
				"ldap://127.0.0.1:" + this.port + "/" + this.root);
		if (this.managerDn != null) {
			contextSourceFromProviderUrl.setUserDn(this.managerDn);
			if (this.managerPassword == null) {
				throw new IllegalStateException("managerPassword is required if managerDn is supplied");
			}
			contextSourceFromProviderUrl.setPassword(this.managerPassword);
		}
		contextSourceFromProviderUrl.afterPropertiesSet();
		return contextSourceFromProviderUrl;
	}

	@Override
	public Class<?> getObjectType() {

View on GitHub (pinned to 96852e8860)

Solutions

  1. Add com.unboundid:unboundid-ldapsdk to the classpath.
  2. If an external LDAP is intended, use <ldap-server url="ldap://host:port/..."/> instead of embedded mode.
  3. Remove the embedded <ldap-server/> element if LDAP isn't needed.

Example fix

// before
<ldap-server ldif="classpath:test-users.ldif"/>

// after (pom.xml)
<dependency>
  <groupId>com.unboundid</groupId>
  <artifactId>unboundid-ldapsdk</artifactId>
</dependency>
Defensive patterns

Strategy: validation

Validate before calling

boolean ok;
try { Class.forName("com.unboundid.ldap.sdk.LDAPServer"); ok = true; }
catch (ClassNotFoundException e) { ok = false; }
if (!ok) throw new IllegalStateException("unboundid-ldapsdk required for embedded LDAP");

Try / catch

try { ctx.refresh(); }
catch (IllegalStateException e) {
  if (e.getMessage().contains("Embedded LDAP server is not provided")) addUnboundIdDep();
}

Prevention

When it happens

Trigger: Using <ldap-server/> with embedded mode while the UnboundID SDK (com.unboundid:unboundid-ldapsdk) is not on the classpath; getObject() invoked with unboundIdPresent == false.

Common situations: Old configs previously backed by ApacheDS (removed in Spring Security 4.x+); dependency management stripping the optional unboundid-ldapsdk; forgetting the embedded LDAP dependency after upgrade.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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