flowable/flowable-engine · error · FlowableIllegalArgumentException

Candidate group is null

Error message

Candidate group is null

What it means

TaskQueryImpl.taskCandidateGroup() throws this when candidateGroup is null. The candidate group filter needs a concrete group id to query task identity links. Null arguments are rejected at query-build time with FlowableIllegalArgumentException.

Solutions

1. Pass a non-null group id string to taskCandidateGroup().
2. Null-check before calling and skip the candidate filter when absent.
3. Resolve the null group id from its upstream source (variable, config, identity provider).
4. If either group or list may apply, choose taskCandidateGroup or taskCandidateGroupIn consistently and guard both inputs.

Example fix

// before
TaskQuery query = taskService.createTaskQuery().taskCandidateGroup(groupId);
// after
TaskQuery query = taskService.createTaskQuery();
if (groupId != null) {
    query = query.taskCandidateGroup(groupId);
}

if (candidateGroup == null) {
    throw new IllegalArgumentException("candidateGroup must be non-null before taskCandidateGroup()");
}
query.taskCandidateGroup(candidateGroup);

boolean isValidCandidateGroup(String g) { return g != null && !g.trim().isEmpty(); }

try {
    query.taskCandidateGroup(groupId);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("Invalid candidate group query: {}", e.getMessage());
    query = taskService.createTaskQuery();
}

When it happens

Trigger: Calling taskQuery.taskCandidateGroup(null), typically when the group id comes from a variable, config property, or expression that evaluated to null.

Common situations: Process variable holding the candidate group unset; tenant/group resolution returned null; code path refactored so the group is no longer populated.

Related errors

• Candidate group list is null
• Assignee is null
• Assignee is null
• AssigneeLike is null
• AssigneeLike is null

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

Appendix: source

Thrown at modules/flowable-task-service/src/main/java/org/flowable/task/service/impl/TaskQueryImpl.java:622

    public TaskQueryImpl taskInvolvedGroups(Collection<String> involvedGroups) {
        if (involvedGroups == null) {
            throw new FlowableIllegalArgumentException("Involved groups are null");
        }
        if (involvedGroups.isEmpty()) {
            throw new FlowableIllegalArgumentException("Involved groups are empty");
        }
        if (orActive) {
            currentOrQueryObject.involvedGroups = involvedGroups;
        } else {
            this.involvedGroups = involvedGroups;
        }
        return this;
    }

    @Override
    public TaskQueryImpl taskCandidateGroup(String candidateGroup) {
        if (candidateGroup == null) {
            throw new FlowableIllegalArgumentException("Candidate group is null");
        }

        if (candidateGroups != null) {
            throw new FlowableIllegalArgumentException("Invalid query usage: cannot set both candidateGroup and candidateGroupIn");
        }

        if (orActive) {
            currentOrQueryObject.candidateGroup = candidateGroup;
        } else {
            this.candidateGroup = candidateGroup;
        }
        return this;
    }

    @Override
    public TaskQuery taskCandidateOrAssigned(String userIdForCandidateAndAssignee) {
        if (candidateGroup != null) {
            throw new FlowableIllegalArgumentException("Invalid query usage: cannot set candidateGroup");

View on GitHub (pinned to d6d39ce1c6)