What causes "ldapConfiguration is not set" in flowable/flowable-engine?

Instantiate an LDAPConfiguration, populate its connection fields, and call ldapConfigurator.setLdapConfiguration(ldapConfiguration) BEFORE the engine is initialized.

flowable/flowable-engine · critical · FlowableException

ldapConfiguration is not set

Error message

ldapConfiguration is not set

What it means

LDAPConfigurator.configure() wires the LDAP identity/proxy setup into a Flowable engine, but it can only do so when an LDAPConfiguration instance has been provided. If the 'ldapConfiguration' field on the configurator is still null when the engine boots, configuration cannot proceed and a FlowableException is thrown immediately, aborting engine startup. This is a fail-fast guard so a misconfigured engine never starts without its LDAP backing.

Source

Thrown at modules/flowable-ldap-configurator/src/main/java/org/flowable/ldap/LDAPConfigurator.java:47

 * 
 * @author Joram Barrez
 */
public class LDAPConfigurator extends IdmEngineConfigurator {

    protected LDAPConfiguration ldapConfiguration;

    @Override
    public void beforeInit(AbstractEngineConfiguration engineConfiguration) {
        // Nothing to do
    }

    @Override
    public void configure(AbstractEngineConfiguration engineConfiguration) {
        
        this.idmEngineConfiguration = new LdapIdmEngineConfiguration();
        
        if (ldapConfiguration == null) {
            throw new FlowableException("ldapConfiguration is not set");
        }

        LDAPGroupCache ldapGroupCache = null;
        if (ldapConfiguration.getGroupCacheSize() > 0) {
            ldapGroupCache = new LDAPGroupCache(ldapConfiguration.getGroupCacheSize(), 
                    ldapConfiguration.getGroupCacheExpirationTime(), engineConfiguration.getClock());
            
            if (ldapConfiguration.getGroupCacheListener() != null) {
                ldapGroupCache.setLdapCacheListener(ldapConfiguration.getGroupCacheListener());
            }
        }
        
        super.configure(engineConfiguration);
        
        getIdmEngineConfiguration(engineConfiguration)
                .setIdmIdentityService(new LDAPIdentityServiceImpl(ldapConfiguration, ldapGroupCache, idmEngineConfiguration));
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Instantiate an LDAPConfiguration, populate its connection fields, and call ldapConfigurator.setLdapConfiguration(ldapConfiguration) BEFORE the engine is initialized.
If using Spring, verify the configurator bean receives the ldapConfiguration bean reference (property/constructor injection).
Ensure the configurator is only added to the engine configuration after the LDAPConfiguration is fully constructed.
Add a startup self-check that asserts getLdapConfiguration() != null before building the process engine.

Example fix

// before
LDAPConfigurator configurator = new LDAPConfigurator();
processEngineConfiguration.setConfigurators(Collections.singletonList(configurator));
// after
LDAPConfigurator configurator = new LDAPConfigurator();
LDAPConfiguration ldapConfiguration = new LDAPConfiguration();
ldapConfiguration.setLdapServer("ldap://localhost");
ldapConfiguration.setPort(10389);
ldapConfiguration.setUser("cn=admin,dc=flowable,dc=org");
ldapConfiguration.setPassword("pass");
ldapConfiguration.setBaseDn("dc=flowable,dc=org");
configurator.setLdapConfiguration(ldapConfiguration);
processEngineConfiguration.setConfigurators(Collections.singletonList(configurator));

Defensive patterns

Strategy: validation

Validate before calling

LDAPConfigurator configurator = new LDAPConfigurator();
if (configurator.getLdapConfiguration() == null) {
    configurator.setLdapConfiguration(buildLdapConfiguration()); // must be set before engine init
}
processEngineConfiguration.setConfigurators(Collections.singletonList(configurator));

Prevention

Always call setLdapConfiguration() immediately after constructing LDAPConfigurator.
In Spring, wire the ldapConfiguration bean reference explicitly in the configurator bean definition.
Assert configurator.getLdapConfiguration() != null in a startup smoke test.
Keep LDAP connection settings in one config object/property file to avoid dropping them during refactors.

When it happens

Trigger: Creating a new LDAPConfigurator() and registering it via engineConfigurator list (e.g. config.setConfigurators/addConfigurator) without ever calling setLdapConfiguration(...). Also when the LDAPConfiguration bean is wired in Spring but the setter is bypassed or the property is missing from the config file.

Common situations: Spring XML/properties wiring where the ldapConfiguration bean reference is missing; copying a bootstrapping snippet that adds the configurator but omits the configuration object; upgrading Flowable and dropping the LDAP config from application context; hand-rolled programmatic engine setup for tests.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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