flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope type is null

Error message

Provided scope type is null

What it means

EventSubscriptionQueryImpl.scopeType() validates its argument before storing it. Flowable throws FlowableIllegalArgumentException when a null scope type is passed, because a null scopeType would silently produce an ill-defined query filter. The library treats query setters as strict API: null is never accepted as a value.

Solutions

1. Check the scopeType value for null before calling scopeType(), and skip the filter or supply a default like "bpmn"
2. Fix the upstream source (variable, config, property file) so a valid scope type is populated
3. If the filter is conditional, only invoke scopeType() when a non-null value exists

Example fix

// before
query.scopeType(processScopeType);

// after
if (processScopeType != null) {
    query.scopeType(processScopeType);
}

if (scopeType == null || scopeType.isBlank()) {
    throw new IllegalArgumentException("scopeType must be set before building query");
}

boolean hasScopeType(String s) { return s != null && !s.isBlank(); }

try {
    query.scopeType(scopeType);
} catch (FlowableIllegalArgumentException e) {
    log.warn("scopeType was null, applying default", e);
    query.scopeType("bpmn");
}

When it happens

Trigger: Calling eventSubscriptionQuery.scopeType(null), e.g. when the scope type comes from an unset variable, a missing BPMN property, or a configuration map lookup that returned null.

Common situations: Passing a scope type read from a process variable or external config that was never populated; refactoring code that previously used scope types like 'bpmn' or 'cmmn' but the source of the value became optional.

Related errors

• configuration is null
• activity tenant id is null
• activityId is null
• batchId is null
• batchSearchKey is null

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

Appendix: source

Thrown at modules/flowable-eventsubscription-service/src/main/java/org/flowable/eventsubscription/service/impl/EventSubscriptionQueryImpl.java:349

    @Override
    public EventSubscriptionQueryImpl scopeDefinitionKey(String scopeDefinitionKey) {
        if (scopeDefinitionKey == null) {
            throw new FlowableIllegalArgumentException("Provided scope definition key is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.scopeDefinitionKey = scopeDefinitionKey;
        } else {
            this.scopeDefinitionKey = scopeDefinitionKey;
        }

        return this;
    }
    
    @Override
    public EventSubscriptionQueryImpl scopeType(String scopeType) {
        if (scopeType == null) {
            throw new FlowableIllegalArgumentException("Provided scope type is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.scopeType = scopeType;
        } else {
            this.scopeType = scopeType;
        }

        return this;
    }

    @Override
    public EventSubscriptionQueryImpl createdBefore(Date beforeTime) {
        if (beforeTime == null) {
            throw new FlowableIllegalArgumentException("created before time is null");
        }

        if (inOrStatement) {

View on GitHub (pinned to d6d39ce1c6)