flowable/flowable-engine · error · FlowableIllegalArgumentException

Set of process definition keys is null

Error message

Set of process definition keys is null

What it means

Flowable's ProcessInstanceQuery.processDefinitionKeys(Set<String>) throws FlowableIllegalArgumentException when the passed set is null. The API requires an actual, non-empty set of process definition keys to build the query condition. Throwing eagerly at query-construction time surfaces the bad argument immediately instead of failing later at query execution.

Solutions

1. Ensure the Set<String> is initialized before calling processDefinitionKeys (e.g. new HashSet<>(Arrays.asList("key1","key2"))).
2. Check the upstream code path producing the set and default it to an empty guard that skips the filter instead of passing null.
3. Wrap the call with a null check and skip the filter condition when the set is absent.
4. Catch FlowableIllegalArgumentException around the query construction and log/propagate a clear client-side message.

Example fix

// before
Set<String> keys = getConfiguredKeys(); // may be null
runtimeService.createProcessInstanceQuery().processDefinitionKeys(keys);
// after
Set<String> keys = getConfiguredKeys();
if (keys != null && !keys.isEmpty()) {
    runtimeService.createProcessInstanceQuery().processDefinitionKeys(keys);
}

if (keys == null || keys.isEmpty()) { throw new IllegalArgumentException("processDefinitionKeys must be a non-empty set"); }
runtimeService.createProcessInstanceQuery().processDefinitionKeys(keys);

boolean isValidKeySet(Set<String> s) { return s != null && !s.isEmpty(); }

try {
    query.processDefinitionKeys(keys);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Invalid processDefinitionKeys argument: {}", e.getMessage());
    throw new BadRequestException(e.getMessage());
}

When it happens

Trigger: Calling processInstanceQuery().processDefinitionKeys(null), e.g. when the set comes from a variable, method parameter, or configuration value that was never initialized.

Common situations: Dynamic query builders that assemble key sets from user input or config; refactors where a default set assignment was removed; deserialized DTOs with a null field passed straight into the query.

Related errors

• Involved user is null
• activatedBefore is null
• activity tenant id is null
• after time is null
• Assignee is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:479

    
    @Override
    public ProcessInstanceQueryImpl processDefinitionKeyLikeIgnoreCase(String processDefinitionKeyLikeIgnoreCase) {
        if (processDefinitionKeyLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Process definition key is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKeyLikeIgnoreCase = processDefinitionKeyLikeIgnoreCase;
        } else {
            this.processDefinitionKeyLikeIgnoreCase = processDefinitionKeyLikeIgnoreCase;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processDefinitionKeys(Set<String> processDefinitionKeys) {
        if (processDefinitionKeys == null) {
            throw new FlowableIllegalArgumentException("Set of process definition keys is null");
        }
        if (processDefinitionKeys.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of process definition keys is empty");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKeys = processDefinitionKeys;
        } else {
            this.processDefinitionKeys = processDefinitionKeys;
        }
        return this;
    }
    
    @Override
    public ProcessInstanceQuery excludeProcessDefinitionKeys(Set<String> excludeProcessDefinitionKeys) {
        if (excludeProcessDefinitionKeys == null) {
            throw new FlowableIllegalArgumentException("Set of process definition keys is null");
        }

View on GitHub (pinned to d6d39ce1c6)