flowable/flowable-engine · error · FlowableIllegalArgumentException

No 'queryUserByFullNameLike' configured

Error message

No 'queryUserByFullNameLike' configured

What it means

LDAPQueryBuilder.buildQueryByFullNameLike builds the LDAP search filter for 'find users where full name like X'. Unlike most other query templates, the Flowable LDAP integration has no built-in default for this filter, so it requires the 'queryUserByFullNameLike' property in the LDAPConfigurator. When it is absent, the builder throws FlowableIllegalArgumentException.

Source

Thrown at modules/flowable-ldap/src/main/java/org/flowable/ldap/LDAPQueryBuilder.java:90

                }

            });

            searchExpression = MessageFormat.format(ldapConfigurator.getQueryGroupsForUser(), Rdn.escapeValue(userDn));

        } else {
            searchExpression = userId;
        }
        return searchExpression;
    }

    public String buildQueryByFullNameLike(final LDAPConfiguration ldapConfigurator, String searchText) {
        String searchExpression = null;
        if (ldapConfigurator.getQueryUserByFullNameLike() != null) {
            searchExpression = MessageFormat.format(ldapConfigurator.getQueryUserByFullNameLike(), ldapConfigurator.getUserFirstNameAttribute(), searchText, ldapConfigurator.getUserLastNameAttribute(),
                    searchText);
        } else {
            throw new FlowableIllegalArgumentException("No 'queryUserByFullNameLike' configured");
        }
        return searchExpression;
    }

    public String buildQueryGroupsById(LDAPConfiguration ldapConfigurator, String groupId) {
        String searchExpression;
        if (ldapConfigurator.getQueryGroupByGroupId() != null) {
            searchExpression = MessageFormat.format(ldapConfigurator.getQueryGroupByGroupId(), groupId);
        } else {
            searchExpression = groupId;
        }
        return searchExpression;
    }

    protected SearchControls createSearchControls(LDAPConfiguration ldapConfigurator) {
        SearchControls searchControls = new SearchControls();
        searchControls.setSearchScope(SearchControls.SUBTREE_SCOPE);
        searchControls.setTimeLimit(ldapConfigurator.getSearchTimeLimit());

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set queryUserByFullNameLike on the LDAPConfigurator, e.g. ldapConfigurator.setQueryUserByFullNameLike("(& (objectclass=inetOrgPerson) (|({0}={1})(_givenName={2}*)(sn={3}*)))") with a MessageFormat pattern matching your schema.
2. Avoid calling userFullNameLike on the LDAP user query until the property is configured.
3. Verify the LDAP configuration actually loaded the property (check that getQueryUserByFullNameLike() returns non-null at startup).

Example fix

// before
LDAPConfigurator cfg = LDAPConfiguratorImpl.fromXml(...); // no queryUserByFullNameLike
List<User> users = cfg.getIdentityService().createUserQuery().userFullNameLike("jo").list();

// after
cfg.setQueryUserByFullNameLike("(& (objectclass=inetOrgPerson) (|({0}={2}*)(displayName={1}*)))");
List<User> users = cfg.getIdentityService().createUserQuery().userFullNameLike("jo").list();

Objects.requireNonNull(ldapConfigurator.getQueryUserByFullNameLike(), "queryUserByFullNameLike must be configured before using userFullNameLike queries");

try { return userQuery.userFullNameLike(pattern).list(); } catch (FlowableIllegalArgumentException e) { log.error("LDAP config missing queryUserByFullNameLike", e); throw e; }

When it happens

Trigger: Executing a UserQuery with .userFullNameLike("...") (e.g. via LDAPIdentityService.createUserQuery().userFullNameLike(...)) while the LDAPConfigurator instance was created without setting queryUserByFullNameLike.

Common situations: Applications that use LDAP user queries for other criteria but only later add a full-name-like search; config files copied from older examples that omit the queryUserByFullNameLike property; upgrades where new query capabilities are used but the LDAP config was not extended.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• transactionManager is required property for SpringIdmEngineC
• ldapConfiguration is not set
• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• Setting a deployment name is not supported for apps

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