flowable/flowable-engine · error · FlowableIllegalArgumentException

executionIds is null

Error message

executionIds is null

What it means

VariableInstanceQuery.executionIds(Set<String>) requires a non-null set of execution ids. Flowable throws FlowableIllegalArgumentException immediately when null is passed, because filtering by an absent collection is meaningless. This is a build-time argument validation; no database query runs.

Solutions

1. Ensure the set is initialized before calling executionIds()
2. Skip calling executionIds() entirely when the collection is null, falling back to an unfiltered query or another filter
3. Default to Collections.emptySet() and branch around the empty case before reaching the query

Example fix

// before
query.executionIds(executionIds); // may be null
// after
if (executionIds != null) {
    query.executionIds(executionIds);
}

if (executionIds == null) {
    throw new IllegalArgumentException("executionIds must be non-null before querying");
}

Set<String> safeSet(Set<String> s) { return s == null ? Collections.emptySet() : s; }

try {
    query.executionIds(executionIds);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().equals("executionIds is null")) {
        // fall back to query without the executionIds filter
    } else { throw e; }
}

When it happens

Trigger: Passing null to executionIds(), e.g. variableInstanceQuery.executionIds(someSetThatIsNull) where the set was never initialized or came from an upstream API returning null.

Common situations: A variable holding execution ids was conditionally populated and ended up null, or a service method forwards an optional id collection straight into the query builder.

Related errors

• taskId is null
• taskIds is null
• Cannot use executionId together with excludeLocalVariables
• Cannot use executionIds together with excludeLocalVariables
• Cannot use taskId together with excludeTaskVariables

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/VariableInstanceQueryImpl.java:101

        return this;
    }

    @Override
    public VariableInstanceQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new FlowableIllegalArgumentException("Execution id is null");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use executionId together with excludeLocalVariables");
        }
        this.executionId = executionId;
        return this;
    }

    @Override
    public VariableInstanceQueryImpl executionIds(Set<String> executionIds) {
        if (executionIds == null) {
            throw new FlowableIllegalArgumentException("executionIds is null");
        }
        if (executionIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of executionIds is empty");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use executionIds together with excludeLocalVariables");
        }
        this.executionIds = executionIds;
        return this;
    }

    public VariableInstanceQuery activityInstanceId(String activityInstanceId) {
        this.activityInstanceId = activityInstanceId;
        return this;
    }

    @Override
    public VariableInstanceQuery taskId(String taskId) {

View on GitHub (pinned to d6d39ce1c6)