flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope definition key is null

Error message

Provided scope definition key is null

What it means

Flowable throws FlowableIllegalArgumentException from EventSubscriptionQueryImpl.scopeDefinitionKey when scopeDefinitionKey() is called with null. The definition key is the model-level identifier (BPMN process id / CMMN case id in the XML) and null is rejected during query building. Pass a non-null key or drop the filter.

Solutions

1. Null-check the key before calling scopeDefinitionKey()
2. Load the key from the process/case definition repository or model and confirm it is present
3. Omit the filter when the key is unknown
4. Use scopeDefinitionId() with a resolved id instead of the key

Example fix

// before
query.scopeDefinitionKey(defKey);

// after
if (defKey != null) {
    query.scopeDefinitionKey(defKey);
}

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

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

try {
    query.scopeDefinitionKey(defKey).list();
} catch (FlowableIllegalArgumentException e) {
    // definition key missing
}

When it happens

Trigger: Calling .scopeDefinitionKey(null), commonly when the key comes from an unset config field, a model attribute that was never read, or shared code where the key is optional.

Common situations: Configuration not loaded so the configured process/case key is null; refactoring where a constant was removed; querying across scope types where the key differs per type.

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/cc30c99e3eba273a. Report an issue: GitHub.

Appendix: source

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

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

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

View on GitHub (pinned to d6d39ce1c6)