flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided element ids are null

Error message

Provided element ids are null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.elementIds() when the caller passes a null Collection. Flowable query builders validate filter arguments eagerly so that a malformed query fails immediately at the call site instead of producing an empty or misleading result set (or a SQL error) when list() is executed. Passing null is considered a programming error, not a valid filter value.

Solutions

1. Do not call elementIds() when the collection is null — apply the filter conditionally
2. Initialize the collection to an empty list (Collections.emptyList()) instead of null
3. Check the upstream producer of the collection so it never returns null
4. If the intent is 'no filter', simply omit the elementIds() call

Example fix

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

if (elementIds != null) {
    query.elementIds(elementIds);
}

boolean hasElementIds = elementIds != null && !elementIds.isEmpty();

try {
    query.elementIds(elementIds);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("element ids are null")) {
        query = taskQueryService.createSuspendedJobQuery(); // rebuild without filter
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().elementIds(null), e.g. when the collection is the result of a method that returned null instead of an empty list, or when an optional variable holding the ids was never initialized.

Common situations: Mapping a variable that is null when the user provided no element-id filter; a service method returning null rather than Collections.emptyList(); refactoring code where an ids parameter became nullable.

Related errors

• Provided element name is null
• bytes is null
• category is null
• categoryLike is null
• categoryNotEquals is null

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:216

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

    @Override
    public SuspendedJobQueryImpl elementIds(Collection<String> elementIds) {
        if (elementIds == null) {
            throw new FlowableIllegalArgumentException("Provided element ids are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.elementIds = elementIds;
        } else {
            this.elementIds = elementIds;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl elementName(String elementName) {
        if (elementName == null) {
            throw new FlowableIllegalArgumentException("Provided element name is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.elementName = elementName;
        } else {
            this.elementName = elementName;

View on GitHub (pinned to d6d39ce1c6)