flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided element name is null

Error message

Provided element name is null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.elementName() when the caller passes a null String. Flowable validates query filter arguments eagerly so a bad query fails at configuration time rather than at execution time. A null element name is not treated as 'no filter'; it is rejected as invalid input.

Solutions

1. Only call elementName() when the value is non-null
2. Coalesce to a sentinel value or omit the filter entirely when null
3. Fix the upstream source so it supplies an empty-string/default instead of null
4. Validate request input before mapping it to the query

Example fix

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

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

boolean hasElementName = elementName != null && !elementName.trim().isEmpty();

try {
    query.elementName(elementName);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("element name is null")) {
        // rebuild query without the elementName filter
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().elementName(null), typically when the name comes from an uninitialized variable, a map lookup that missed, or an optional request parameter bound as null.

Common situations: REST request fields left unset and passed straight into the query; configuration lookups returning null for a missing element name; tests passing null to probe behavior.

Related errors

• Provided element ids are 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/342ed33571d5889f. Report an issue: GitHub.

Appendix: source

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

    }

    @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;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl scopeId(String scopeId) {
        if (scopeId == null) {
            throw new FlowableIllegalArgumentException("Provided scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeId = scopeId;
        } else {
            this.scopeId = scopeId;

View on GitHub (pinned to d6d39ce1c6)