flowable/flowable-engine · error · ActivitiIllegalArgumentException

Set of process definition ids is empty

Error message

Set of process definition ids is empty

What it means

ProcessInstanceQueryImpl.processDefinitionIds(Set<String>) throws ActivitiIllegalArgumentException with message 'Set of process definition ids is empty' when the set is non-null but has no elements. An empty IN clause is invalid SQL semantically (it would match nothing or be unparseable), so the API rejects it upfront. If you want no filtering, do not call the method at all.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:251

        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("Process definition id is null");
        }

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

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

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

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

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionKey = processDefinitionKey;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Check set size before calling; if empty, either return an empty result immediately without executing the query or omit the filter if 'all' is intended.
2. Decide semantics explicitly: empty allowed-set usually means 'no access', so short-circuit to an empty response rather than querying.
3. Ensure upstream data (allowed definitions, tenant config) is loaded and non-empty where it is required.
4. Catch ActivitiIllegalArgumentException and translate it into a business-level message about no accessible definitions.

Example fix

// before
Set<String> ids = loadAllowedDefinitionIds(user);
ProcessInstanceQuery q = query.processDefinitionIds(ids); // throws when empty
// after
Set<String> ids = loadAllowedDefinitionIds(user);
if (ids.isEmpty()) return Collections.emptyList();
ProcessInstanceQuery q = query.processDefinitionIds(ids);

if (ids != null && ids.isEmpty()) {
    return Collections.emptyList(); // empty allowed-set means no accessible definitions
}
if (ids != null) {
    query = query.processDefinitionIds(ids);
}

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

try {
    result = query.processDefinitionIds(ids).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("process definition ids is empty")) {
        return Collections.emptyList(); // semantically: nothing matches an empty IN clause
    }
    throw e;
}

When it happens

Trigger: Calling .processDefinitionIds(Collections.emptySet()) or passing a set that was filtered down to zero elements before query construction — common when authorization or tenant filtering removes all candidates.

Common situations: Access-control logic that yields an empty allowed-definitions set; downstream filtering (stream().filter()) emptying a populated list; loading ids from an empty DB table or missing config.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• rootScopeIds is null or empty
• Set of process instance ids is empty
• process instance tenant id is null
• Process definition category is null
• Process definition name is null

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