What causes "Provided id list is null" in flowable/flowable-engine?

Pass an empty list (or skip the groupIds() call) when there are no ids to filter on.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided id list is null

Error message

Provided id list is null

What it means

Fluent-setter validation in GroupQueryImpl.groupIds: a null id List was passed as the group-id collection filter; the builder rejects it so 'no filter' and 'null filter' stay distinguishable.

Solutions

Pass an empty list (or skip the groupIds() call) when there are no ids to filter on.
Normalize null collections to Collections.emptyList() before building the query.
Ensure upstream deserialization defaults missing arrays to empty lists.
Use Objects.requireNonNullElse(ids, List.of()) style normalization at the boundary.

Example fix

// before
List<String> ids = payload.getGroupIds(); // null when field absent
Group g = identityService.createGroupQuery().groupIds(ids).singleResult();
// after
List<String> ids = payload.getGroupIds();
if (ids != null && !ids.isEmpty()) {
    query = query.groupIds(ids);
}
Group g = query.singleResult();

Defensive patterns

Strategy: validation

Validate before calling

List<String> ids = payload.getGroupIds() == null ? Collections.emptyList() : payload.getGroupIds();
GroupQuery q = identityService.createGroupQuery();
if (!ids.isEmpty()) q = q.groupIds(ids);

Type guard

static List<String> orEmpty(List<String> list) { return list == null ? Collections.emptyList() : list; }

Try / catch

try {
    q = q.groupIds(ids);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("groupIds must not be null", e);
}

Prevention

Default deserialized collection fields to empty lists (e.g. new ArrayList<>() initializers).
Skip criteria whose collections are null or empty rather than passing them.
Normalize null collections at API boundaries with Objects.requireNonNullElse.
Never let helper methods return null collections.

When it happens

Trigger: Calling .groupIds(null) — e.g. the list comes from an unpopulated collection, an Optional chain, or a method returning null instead of an empty list.

Common situations: Batch lookups where the caller's collection was never initialized, deserialized JSON bodies with a missing array field mapped to null, helper methods returning null on 'no ids'.

Related errors

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

Appendix: source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/GroupQueryImpl.java:67

    }

    public GroupQueryImpl(CommandExecutor commandExecutor) {
        super(commandExecutor);
    }

    @Override
    public GroupQuery groupId(String id) {
        if (id == null) {
            throw new FlowableIllegalArgumentException("Provided id is null");
        }
        this.id = id;
        return this;
    }

    @Override
    public GroupQuery groupIds(List<String> ids) {
        if (ids == null) {
            throw new FlowableIllegalArgumentException("Provided id list is null");
        }
        this.ids = ids;
        return this;
    }

    @Override
    public GroupQuery groupName(String name) {
        if (name == null) {
            throw new FlowableIllegalArgumentException("Provided name is null");
        }
        this.name = name;
        return this;
    }

    @Override
    public GroupQuery groupNameLike(String nameLike) {
        if (nameLike == null) {
            throw new FlowableIllegalArgumentException("Provided name is null");

View on GitHub (pinned to d6d39ce1c6)