What causes "ids are null" in flowable/flowable-engine?

Pass a non-null Set, e.g. new HashSet<>(Arrays.asList("dep1","dep2"))

flowable/flowable-engine · error · ActivitiIllegalArgumentException

ids are null

Error message

ids are null

What it means

ProcessDefinitionQueryImpl.deploymentIds(Set<String>) throws ActivitiIllegalArgumentException 'ids are null' when the supplied set is null (an empty set is accepted). The engine needs a concrete collection to build the IN clause, so it rejects null up front. This is an argument contract check in the query builder.

Solutions

Pass a non-null Set, e.g. new HashSet<>(Arrays.asList("dep1","dep2"))
If the filter is optional, only call deploymentIds when the set is non-null
Treat 'no filter' as an empty set only if the rest of the query logic supports it, otherwise omit the call
Catch ActivitiIllegalArgumentException to map it to a client validation error

Example fix

// before
query.deploymentIds(deploymentIdSet); // null when config missing
// after
if (deploymentIdSet != null && !deploymentIdSet.isEmpty()) {
    query.deploymentIds(deploymentIdSet);
}

Defensive patterns

Strategy: validation

Validate before calling

if (deploymentIds == null) throw new IllegalArgumentException("deploymentIds set is required");
query.deploymentIds(deploymentIds);

Type guard

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

Try / catch

try {
    query.deploymentIds(ids);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("ids are null")) {
        throw new BadRequestException("deploymentIds must not be null");
    }
    throw e;
}

Prevention

Initialize collections to empty sets rather than leaving fields null
Use Collections.emptySet() as the default for optional set filters
Null-check collection parameters before passing them to query builders
Ensure deserialized DTOs default set fields to empty collections

When it happens

Trigger: Calling ProcessDefinitionQuery.deploymentIds(null), e.g. when a collection variable was never initialized, a mapping function returned null instead of an empty set, or an optional bulk filter is forwarded unconditionally.

Common situations: Batch/report code building multi-deployment filters from configuration lists that are absent; Java 8 streams collector results assigned to null on error paths; deserialized DTOs with null set fields.

Related errors

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessDefinitionQueryImpl.java:150

            throw new ActivitiIllegalArgumentException("nameLike is null");
        }
        this.nameLike = nameLike;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl deploymentId(String deploymentId) {
        if (deploymentId == null) {
            throw new ActivitiIllegalArgumentException("id is null");
        }
        this.deploymentId = deploymentId;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl deploymentIds(Set<String> deploymentIds) {
        if (deploymentIds == null) {
            throw new ActivitiIllegalArgumentException("ids are null");
        }
        this.deploymentIds = deploymentIds;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKey(String key) {
        if (key == null) {
            throw new ActivitiIllegalArgumentException("key is null");
        }
        this.key = key;
        return this;
    }

    @Override
    public ProcessDefinitionQueryImpl processDefinitionKeyLike(String keyLike) {
        if (keyLike == null) {
            throw new ActivitiIllegalArgumentException("keyLike is null");

View on GitHub (pinned to d6d39ce1c6)