flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided job id list is null

Error message

Provided job id list is null

What it means

ExternalWorkerJobQuery.jobIds(Collection<String>) throws FlowableIllegalArgumentException when the caller passes a null job-id collection. Flowable query builders validate arguments eagerly so that a null filter never silently turns into an unfiltered or broken SQL query. Passing null is always a programming mistake; pass an empty collection or skip the filter instead.

Solutions

1. Pass an actual collection (e.g. Collections.emptyList()) instead of null.
2. Guard the call site: only invoke jobIds(ids) when ids != null.
3. If the filter is optional, use the query without the jobIds criterion so results are not over/under-filtered.
4. Initialize collection fields with a default empty list at construction time.

Example fix

// before
List<String> ids = params.get("jobIds");
query.jobIds(ids); // NPE-free but throws FlowableIllegalArgumentException
// after
List<String> ids = params.getOrDefault("jobIds", Collections.emptyList());
if (!ids.isEmpty()) {
    query.jobIds(ids);
}

if (jobIds != null && !jobIds.isEmpty()) {
    query.jobIds(jobIds);
}

boolean hasJobIds(Collection<String> ids) { return ids != null && !ids.isEmpty(); }

try {
    query.jobIds(jobIds);
} catch (FlowableIllegalArgumentException e) {
    // fall back to unfiltered query or rethrow with context
}

When it happens

Trigger: Calling externalWorkerJobQuery().jobIds(null), e.g. when the collection is the result of a map lookup or an optional field that was never initialized.

Common situations: Building queries dynamically from user input or config where a list of job ids is optional and null slips through; refactoring code that previously built a list conditionally; deserializing a request payload where 'jobIds' is absent.

Related errors

• after time is null
• decision tenantId is null
• groupId is null
• identityLinkType is null
• involvedGroups are null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/ExternalWorkerJobQueryImpl.java:113

    }

    @Override
    public ExternalWorkerJobQuery jobId(String jobId) {
        if (jobId == null) {
            throw new FlowableIllegalArgumentException("Provided job id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.id = jobId;
        } else {
            this.id = jobId;
        }
        return this;
    }

    @Override
    public ExternalWorkerJobQuery jobIds(Collection<String> jobIds) {
        if (jobIds == null) {
            throw new FlowableIllegalArgumentException("Provided job id list is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.jobIds = jobIds;
        } else {
            this.jobIds = jobIds;
        }
        return this;
    }

    @Override
    public ExternalWorkerJobQuery processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided process instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceId = processInstanceId;
        } else {
            this.processInstanceId = processInstanceId;

View on GitHub (pinned to d6d39ce1c6)