flowable/flowable-engine · error · FlowableIllegalArgumentException

taskIds is null

Error message

taskIds is null

What it means

VariableInstanceQuery.taskIds(Set<String>) requires a non-null set. Passing null throws FlowableIllegalArgumentException immediately at query-build time because an absent id collection cannot form a valid filter.

Solutions

1. Initialize the set before use and only call taskIds() when non-null
2. Skip the taskIds() filter when the collection is null and apply other criteria
3. Return an empty/default result early instead of building the query

Example fix

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

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

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

try {
    query.taskIds(taskIds);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().equals("taskIds is null")) {
        // rebuild query without taskIds filter
    } else { throw e; }
}

When it happens

Trigger: Passing null to taskIds(), e.g. query.taskIds(taskIdsFromUpstream) where the upstream set was never created or a lookup returned null.

Common situations: Batch code aggregating task ids across processes where no tasks matched, leaving the collection null; or optional parameter plumbing that forwards null.

Related errors

• executionIds is null
• taskId 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/d82d45c277fe479d. Report an issue: GitHub.

Appendix: source

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

    @Override
    public VariableInstanceQuery taskId(String taskId) {
        if (taskId == null) {
            throw new FlowableIllegalArgumentException("taskId is null");
        }
        if (excludeTaskRelated) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeTaskVariables");
        }
        if (excludeLocalVariables) {
            throw new FlowableIllegalArgumentException("Cannot use taskIds together with excludeLocalVariables");
        }
        this.taskId = taskId;
        return this;
    }

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

    @Override
    public VariableInstanceQuery excludeTaskVariables() {
        if (taskId != null) {
            throw new FlowableIllegalArgumentException("Cannot use taskId together with excludeTaskVariables");

View on GitHub (pinned to d6d39ce1c6)