flowable/flowable-engine · critical · FlowableException

Could not create InitialDirContext for LDAP connection:

Error message

Could not create InitialDirContext for LDAP connection: 

What it means

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.

Solutions

1. Check that the LDAP server is reachable: verify host/port in LDAPConfiguration (setLdapServer/setPort) and test with 'ldapsearch -H ldap://host:port'.
2. Validate the bind DN and password configured via setUser/setPassword by binding manually with ldapwhoami.
3. Inspect the wrapped NamingException message (logged as WARN) for the root cause code (e.g. 49 = invalid credentials, 81 = server down).
4. If using TLS, ensure the truststore contains the LDAP server certificate and the URL scheme/StartTLS settings match.
5. Fix DNS/hostname resolution if deployed in containers; use the service name and correct port.

Example fix

// before
ldapConfiguration.setLdapServer("ldap://localhost");
ldapConfiguration.setPort(10389); // server actually on 389
// after
ldapConfiguration.setLdapServer("ldap://ldap.mycompany.com");
ldapConfiguration.setPort(389);
ldapConfiguration.setUser("cn=flowable,ou=system,dc=mycompany,dc=com");
ldapConfiguration.setPassword("correct-password");

// Pre-flight connectivity check before engine use
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress("ldap.mycompany.com", 389), 3000); // fails fast if unreachable
} catch (IOException e) {
    throw new IllegalStateException("LDAP server unreachable, check host/port/firewall", e);
}

try {
    identityService.createUserQuery().userId("test").singleResult();
} catch (FlowableException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not create InitialDirContext")) {
        // log root cause, check server up / credentials / TLS, then retry or fail startup
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Could not create InitialDirContext for LDAP connection
• Could not find groups
• Null or empty passwords are not allowed!
• An error occurs creating a web-service client for WSDL '" +…
• Authentication failed for this username and password

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

Appendix: source

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

        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)