{"record":{"id":"8d9673897f9e320b","repo":"flowable/flowable-engine","slug":"could-not-create-initialdircontext-for-ldap-connec","errorCode":null,"errorMessage":"Could not create InitialDirContext for LDAP connection: ","messagePattern":"Could not create InitialDirContext for LDAP connection: ","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-ldap/src/main/java/org/flowable/ldap/LDAPConnectionUtil.java","lineNumber":61,"sourceCode":"        properties.put(Context.SECURITY_PRINCIPAL, principal);\n        properties.put(Context.SECURITY_CREDENTIALS, credentials);\n\n        if (ldapConfigurator.isConnectionPooling()) {\n            properties.put(\"com.sun.jndi.ldap.connect.pool\", \"true\");\n        }\n\n        if (ldapConfigurator.getCustomConnectionParameters() != null) {\n            for (String customParameter : ldapConfigurator.getCustomConnectionParameters().keySet()) {\n                properties.put(customParameter, ldapConfigurator.getCustomConnectionParameters().get(customParameter));\n            }\n        }\n\n        InitialDirContext context;\n        try {\n            context = new InitialDirContext(properties);\n        } catch (NamingException e) {\n            LOGGER.warn(\"Could not create InitialDirContext for LDAP connection: {}\", e.getMessage());\n            throw new FlowableException(\"Could not create InitialDirContext for LDAP connection: \" + e.getMessage(), e);\n        }\n        return context;\n    }\n\n    public static void closeDirectoryContext(InitialDirContext initialDirContext) {\n        try {\n            initialDirContext.close();\n        } catch (NamingException e) {\n            LOGGER.warn(\"Could not close InitialDirContext correctly!\", e);\n        }\n    }\n\n}\n","sourceCodeStart":43,"sourceCodeEnd":75,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-ldap/src/main/java/org/flowable/ldap/LDAPConnectionUtil.java#L43-L75","documentation":"LDAPConnectionUtil.createDirectoryContext() builds a JNDI InitialDirContext from the LDAPConfiguration properties. When the LDAP server cannot be reached, or credentials/bind DN are rejected, javax.naming.NamingException is caught, logged as a warning, and rethrown as a FlowableException with the underlying NamingException message appended. It wraps any failure to establish the LDAP bind/connection.","triggerScenarios":"new InitialDirContext(properties) throws NamingException: wrong ldap:// host or port, server down, refused connection, TLS/startTLS mismatch, invalid bind DN or password, malformed base DN, or DNS resolution failure.","commonSituations":"LDAP server not running (e.g. embedded ApacheDS test server not started before the engine), firewall blocking port 389/636, typo in bind credentials, using plaintext port where SSL is required, container networking/DNS issues in Kubernetes, anonymous bind disabled while no user/password configured.","solutions":["Check that the LDAP server is reachable: verify host/port in LDAPConfiguration (setLdapServer/setPort) and test with 'ldapsearch -H ldap://host:port'.","Validate the bind DN and password configured via setUser/setPassword by binding manually with ldapwhoami.","Inspect the wrapped NamingException message (logged as WARN) for the root cause code (e.g. 49 = invalid credentials, 81 = server down).","If using TLS, ensure the truststore contains the LDAP server certificate and the URL scheme/StartTLS settings match.","Fix DNS/hostname resolution if deployed in containers; use the service name and correct port."],"exampleFix":"// before\nldapConfiguration.setLdapServer(\"ldap://localhost\");\nldapConfiguration.setPort(10389); // server actually on 389\n// after\nldapConfiguration.setLdapServer(\"ldap://ldap.mycompany.com\");\nldapConfiguration.setPort(389);\nldapConfiguration.setUser(\"cn=flowable,ou=system,dc=mycompany,dc=com\");\nldapConfiguration.setPassword(\"correct-password\");","handlingStrategy":"try-catch","validationCode":"// Pre-flight connectivity check before engine use\ntry (Socket s = new Socket()) {\n    s.connect(new InetSocketAddress(\"ldap.mycompany.com\", 389), 3000); // fails fast if unreachable\n} catch (IOException e) {\n    throw new IllegalStateException(\"LDAP server unreachable, check host/port/firewall\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    identityService.createUserQuery().userId(\"test\").singleResult();\n} catch (FlowableException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Could not create InitialDirContext\")) {\n        // log root cause, check server up / credentials / TLS, then retry or fail startup\n    }\n}","preventionTips":["Verify host/port/bind credentials with ldapsearch/ldapwhoami before wiring them into LDAPConfiguration.","Start embedded LDAP test servers (e.g. ApacheDS/UnboundID in-memory) before engine initialization in tests.","Keep the NamingException message from the WARN log — its LDAP error code names the root cause.","For ldaps://, preinstall the server certificate in the JVM truststore.","Use hostnames resolvable in the deployment environment (container DNS), not localhost, in cluster setups."],"tags":["ldap","jndi","connection","network","authentication"],"backgroundTag":"connection-refused","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}