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

Apply scopeIds() conditionally only when the collection is non-null

flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope ids are null

Error message

Provided scope ids are null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.scopeIds() when the caller passes a null Collection of scope ids. Like all Flowable query filters, a null collection is rejected as invalid input; an empty collection is the correct way to express 'no ids' if that is supported by the caller's logic. The check fails fast so the query cannot be built in an inconsistent state.

Solutions

Apply scopeIds() conditionally only when the collection is non-null
Default the collection to Collections.emptyList() where empty semantics are intended
Correct upstream deserialization to produce empty collections instead of null
Check the aggregation logic so it never returns a null list

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

boolean hasScopeIds = scopeIds != null && !scopeIds.isEmpty();

Try / catch

try {
    query.scopeIds(scopeIds);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("scope ids are null")) {
        // rebuild query without the scopeIds filter
    } else {
        throw e;
    }
}

Prevention

Ensure JSON deserialization yields empty collections, never null (init fields to new ArrayList<>())
Return empty collections from aggregation helpers
Check both null and emptiness before applying IN-style filters
Add tests for 'no ids provided' query paths

When it happens

Trigger: Calling suspendedJobQuery().scopeIds(null), usually when a list of ids was computed by a method that returned null, or a JSON/REST payload omitted the ids array and it was deserialized as null.

Common situations: Optional batch filters assembled dynamically; deserialization of missing JSON arrays into null; aggregating ids from multiple sources where one source is missing.

Related errors

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

Appendix: source

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

    }
    
    @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;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl scopeIds(Collection<String> scopeIds) {
        if (scopeIds == null) {
            throw new FlowableIllegalArgumentException("Provided scope ids are null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeIds = scopeIds;
        } else {
            this.scopeIds = scopeIds;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl withoutScopeId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeId = true;
        } else {
            this.withoutScopeId = true;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)