{"record":{"id":"34d1c5e7b61e5cbf","repo":"spring-projects/spring-security","slug":"embedded-ldap-server-is-not-provided","errorCode":null,"errorMessage":"Embedded LDAP server is not provided","messagePattern":"Embedded LDAP server is not provided","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"config/src/main/java/org/springframework/security/config/annotation/authentication/configurers/ldap/LdapAuthenticationProviderConfigurer.java","lineNumber":583,"sourceCode":"\t\t\t\tcontextSource.setUserDn(this.managerDn);\n\t\t\t\tif (this.managerPassword == null) {\n\t\t\t\t\tthrow new IllegalStateException(\"managerPassword is required if managerDn is supplied\");\n\t\t\t\t}\n\t\t\t\tcontextSource.setPassword(this.managerPassword);\n\t\t\t}\n\t\t\tcontextSource = postProcess(contextSource);\n\t\t\treturn contextSource;\n\t\t}\n\n\t\tprivate void startEmbeddedLdapServer() {\n\t\t\tif (unboundIdPresent) {\n\t\t\t\tUnboundIdContainer unboundIdContainer = new UnboundIdContainer(this.root, this.ldif);\n\t\t\t\tunboundIdContainer.setPort(getPort());\n\t\t\t\tpostProcess(unboundIdContainer);\n\t\t\t\tthis.port = unboundIdContainer.getPort();\n\t\t\t}\n\t\t\telse {\n\t\t\t\tthrow new IllegalStateException(\"Embedded LDAP server is not provided\");\n\t\t\t}\n\t\t}\n\n\t\tprivate int getPort() {\n\t\t\tif (this.port == null) {\n\t\t\t\tthis.port = getDefaultPort();\n\t\t\t}\n\t\t\treturn this.port;\n\t\t}\n\n\t\tprivate int getDefaultPort() {\n\t\t\ttry (ServerSocket serverSocket = new ServerSocket(DEFAULT_PORT, 50, InetAddress.getLoopbackAddress())) {\n\t\t\t\treturn serverSocket.getLocalPort();\n\t\t\t}\n\t\t\tcatch (IOException ex) {\n\t\t\t\treturn RANDOM_PORT;\n\t\t\t}\n\t\t}","sourceCodeStart":565,"sourceCodeEnd":601,"githubUrl":"https://github.com/spring-projects/spring-security/blob/96852e8860138a482cb13d1479573f24ff6443c6/config/src/main/java/org/springframework/security/config/annotation/authentication/configurers/ldap/LdapAuthenticationProviderConfigurer.java#L565-L601","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the embedded LDAP SDK dependency: com.unboundid:unboundid-ldapsdk, so the embedded server can start.","Or configure an external server explicitly via .contextSource().url(\"ldap://host:389/dc=example,dc=com\").","If using a custom ContextSource, set it via contextSourceConfiguration so build() does not fall into the error branch.","Verify the ldif/root settings only when embedding; otherwise provide the external URL."],"exampleFix":"// before\nauth.ldapAuthentication().userSearchFilter(\"(uid={0})\"); // no LDAP source\n// after\nauth.ldapAuthentication().userSearchFilter(\"(uid={0})\")\n    .contextSource().url(\"ldap://ldap.example.com:389/dc=example,dc=com\");","handlingStrategy":"validation","validationCode":"// ensure an LDAP source exists before building\nboolean hasExternal = ldapUrl != null && !ldapUrl.isBlank();\nboolean hasEmbeddedSdk = ClassUtils.isPresent(\"com.unboundid.ldap.sdk.LDAPServer\", getClass().getClassLoader());\nif (!hasExternal && !hasEmbeddedSdk) {\n    throw new IllegalStateException(\"Configure contextSource().url(...) or add unboundid-ldapsdk for embedded LDAP\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    ldapAuth.build();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"Embedded LDAP server\")) {\n        throw new ConfigurationException(\"No LDAP source configured: provide contextSource().url or embedded SDK\", e);\n    }\n    throw e;\n}","preventionTips":["Add com.unboundid:unboundid-ldapsdk when relying on embedded LDAP","Always set an explicit contextSource().url(...) for production","Validate LDAP connectivity at application startup","Keep ldif/root settings only for embedded usage"],"tags":["ldap","configuration","embedded-server","missing-dependency"],"backgroundTag":"missing-required-config","analyzedSha":"96852e8860138a482cb13d1479573f24ff6443c6","analyzedAt":"2026-09-10T23:25:23.477Z","contentChangedAt":"2026-09-10T23:25:23.477Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}