flowable/flowable-engine · error

Could not create InitialDirContext for LDAP connection

Error message

Could not create InitialDirContext for LDAP connection: {}

What it means

Thrown by LDAPConnectionUtil.createDirectoryContext when javax.naming's InitialDirContext cannot be established with the configured LDAP properties; the underlying NamingException is wrapped in a FlowableException. This is almost always a connectivity, authentication, or configuration problem with the LDAP server.

Solutions

1. Verify the LDAP URL, port, and that the server is reachable (e.g. telnet/ldapsearch to host:port)
2. Validate the bind DN and password with ldapsearch -x -H <url> -D <bindDn> -w <password>
3. Check the exception's chained NamingException detail (e.g. 'Connection refused', 'Invalid credentials', 'SSLHandshakeException') for the exact cause
4. For ldaps, import the server certificate into the JVM truststore (-Djavax.net.ssl.trustStore=...)
5. Review the FlowableLdapProperties/ldap invoker configuration for typos

Example fix

// before
ldap.host=ldap.mycompany.com
ldap.port=389
ldap.user=cn=admin,dc=mycompany,dc=corp   // wrong base DN
// after (verified with ldapsearch)
ldap.host=ldap.mycompany.com
ldap.port=389
ldap.user=cn=admin,ou=people,dc=mycompany,dc=com
ldap.password=correct-password

// pre-flight LDAP connectivity + bind check before engine start
Hashtable<String,Object> env = new Hashtable<>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://ldap.mycompany.com:389");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, bindDn);
env.put(Context.SECURITY_CREDENTIALS, password);
try { new InitialDirContext(env).close(); } catch (NamingException e) { throw new IllegalStateException("LDAP preflight failed: " + e.getMessage()); }

try {
    ctx = LDAPConnectionUtil.createDirectoryContext(ldapConfig);
} catch (FlowableException e) {
    log.error("LDAP bind failed: {}", e.getMessage());
    // fail fast or fall back to cached auth
}

When it happens

Trigger: Wrong LDAP URL/host/port, unreachable server, invalid bind DN or credentials, bad security protocol (simple vs SSL), malformed java.naming properties passed to the context.

Common situations: LDAP server hostname typo or firewall blocking port 389/636; expired or wrong service-account password; using ldaps:// without configured truststore (certificate issues); Flowable IDM LDAP invoker misconfigured in flowable.properties.

Related errors

• Could not close InitialDirContext correctly!
• Authentication failed for this username and password
• Could not create InitialDirContext for LDAP connection:
• Could not find groups
• Null or empty passwords are not allowed!

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/70355442acc5aed2. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-ldap/src/main/java/org/flowable/ldap/LDAPConnectionUtil.java:60

        properties.put(Context.SECURITY_AUTHENTICATION, ldapConfigurator.getSecurityAuthentication());
        properties.put(Context.SECURITY_PRINCIPAL, principal);
        properties.put(Context.SECURITY_CREDENTIALS, credentials);

        if (ldapConfigurator.isConnectionPooling()) {
            properties.put("com.sun.jndi.ldap.connect.pool", "true");
        }

        if (ldapConfigurator.getCustomConnectionParameters() != null) {
            for (String customParameter : ldapConfigurator.getCustomConnectionParameters().keySet()) {
                properties.put(customParameter, ldapConfigurator.getCustomConnectionParameters().get(customParameter));
            }
        }

        InitialDirContext context;
        try {
            context = new InitialDirContext(properties);
        } catch (NamingException e) {
            LOGGER.warn("Could not create InitialDirContext for LDAP connection: {}", e.getMessage());
            throw new FlowableException("Could not create InitialDirContext for LDAP connection: " + e.getMessage(), e);
        }
        return context;
    }

    public static void closeDirectoryContext(InitialDirContext initialDirContext) {
        try {
            initialDirContext.close();
        } catch (NamingException e) {
            LOGGER.warn("Could not close InitialDirContext correctly!", e);
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)