flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope definition id is null

Error message

Provided scope definition id is null

What it means

Flowable throws FlowableIllegalArgumentException from EventSubscriptionQueryImpl.scopeDefinitionId when scopeDefinitionId() is called with null. This filter narrows subscriptions to a specific process or case definition id and null is rejected at build time. Provide a non-null definition id or skip the filter.

Solutions

1. Null-check the definition id before applying the filter
2. Resolve the definition id first (process or case definition query) and confirm it exists
3. Omit the filter when no definition constraint is needed
4. Verify you are passing the definition id, not the instance/scope id

Example fix

// before
query.scopeDefinitionId(defId);

// after
if (defId != null) {
    query.scopeDefinitionId(defId);
}

if (scopeDefinitionId == null) {
    throw new IllegalStateException("scopeDefinitionId required");
}
query.scopeDefinitionId(scopeDefinitionId);

if (id instanceof String && !((String) id).isEmpty()) { /* safe to filter */ }

try {
    query.scopeDefinitionId(defId).list();
} catch (FlowableIllegalArgumentException e) {
    // definition id unresolved
}

When it happens

Trigger: Calling .scopeDefinitionId(null), typically when the definition id was not resolved (missing deployment) or when shared code passes whichever definition id variable happens to be null for the current scope type.

Common situations: Definition lookup by key returned no result; BPMN/CMMN shared helpers where only one of processDefinitionId/caseDefinitionId is set; confusing scopeDefinitionId with scopeId.

Related errors

• categoryLike is null
• categoryNotEquals is null
• key is null
• keyLike is null
• name is null

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

Appendix: source

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

        return this;
    }
    
    @Override
    public EventSubscriptionQueryImpl withoutScopeId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeId = true;
        } else {
            this.withoutScopeId = true;
        }

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

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

        return this;
    }
    
    @Override
    public EventSubscriptionQueryImpl withoutScopeDefinitionId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeDefinitionId = true;
        } else {
            this.withoutScopeDefinitionId = true;
        }

View on GitHub (pinned to d6d39ce1c6)