What causes "Process definition keys is null" in flowable/flowable-engine?

Pass a non-null Set of process definition keys, e.g. processDefinitionKeys(Set.of("orderProcess"))

flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition keys is null

Error message

Process definition keys is null

What it means

ExecutionQueryImpl.processDefinitionKeys() validates its Set<String> argument before storing it in the query. Flowable throws FlowableIllegalArgumentException immediately when the caller passes null, because a null key set cannot be translated into a SQL IN clause and silently ignoring it would produce misleading query results. The error is raised eagerly at query-building time, not when the query is executed.

Solutions

Pass a non-null Set of process definition keys, e.g. processDefinitionKeys(Set.of("orderProcess"))
If the caller has no keys, skip the processDefinitionKeys() call entirely instead of passing null
Use processDefinitionKey(String) for a single key when the set semantics are not needed
Coerce upstream nulls to an empty or default key set before building the query

Example fix

// before
executionQuery.processDefinitionKeys(config.getDefinitionKeys()); // NPE-ish FlowableIllegalArgumentException when null
// after
Set<String> keys = config.getDefinitionKeys();
if (keys != null && !keys.isEmpty()) {
    executionQuery.processDefinitionKeys(keys);
}

Defensive patterns

Strategy: validation

Validate before calling

if (keys == null || keys.isEmpty()) throw new IllegalArgumentException("processDefinitionKeys must be a non-null, non-empty set");
query.processDefinitionKeys(keys);

Type guard

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

Try / catch

try {
    query.processDefinitionKeys(keys);
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    log.warn("Invalid processDefinitionKeys argument: {}", e.getMessage());
}

Prevention

Null-check all query filter values collected from config/REST input before applying them
Initialize collections as empty Sets, never null
Wrap query building in a small builder that skips null filters
Add unit tests exercising each query filter with a null argument

When it happens

Trigger: Calling executionQuery.processDefinitionKeys(null) (directly or via an or() block) on an ExecutionQuery obtained from runtimeService.createExecutionQuery().

Common situations: Building queries from configuration maps or REST request parameters where the 'processDefinitionKeys' field is absent/null; collecting keys into a Set that ends up empty and null due to an upstream lookup returning null instead of an empty set.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:444

                throw new FlowableIllegalArgumentException("Business key is null");
            }
            
            if (inOrStatement) {
                this.currentOrQueryObject.businessKeyLikeIgnoreCase = processInstanceBusinessKeyLikeIgnoreCase;
                this.currentOrQueryObject.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;
            } else {
                this.businessKeyLikeIgnoreCase = processInstanceBusinessKeyLikeIgnoreCase;
                this.includeChildExecutionsWithBusinessKeyQuery = includeChildExecutions;
            }
            
            return this;
        }
    }

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

View on GitHub (pinned to d6d39ce1c6)