flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided scope type is null

Error message

Provided scope type is null

What it means

JobQueryImpl.scopeType(String) validates that the scope type filter is non-null and throws FlowableIllegalArgumentException otherwise. Scope type (e.g. ScopeTypes.BPMN or ScopeTypes.CMMN) tells the job query which engine partition to search; a null type would make the query ambiguous, so it is rejected immediately. Note this method is also invoked internally by caseInstanceId/caseDefinitionId/planItemInstanceId, but those already null-check their own inputs first.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/JobQueryImpl.java:291

    }

    @Override
    public JobQueryImpl subScopeId(String subScopeId) {
        if (subScopeId == null) {
            throw new FlowableIllegalArgumentException("Provided sub scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.subScopeId = subScopeId;
        } else {
            this.subScopeId = subScopeId;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid ScopeTypes constant (BPMN or CMMN) instead of null
2. Validate the scope-type variable before calling; default to a known constant when unset
3. Fix the config/lookup that was supposed to yield the scope type
4. If scope filtering is not needed, omit the call rather than passing null

Example fix

// before
jobQuery.scopeType(scopeType); // scopeType may be null
// after
if (scopeType != null) {
    jobQuery.scopeType(scopeType);
} else {
    jobQuery.scopeType(ScopeTypes.BPMN);
}

if (scopeType == null) { scopeType = ScopeTypes.BPMN; }
jobQuery.scopeType(scopeType);

boolean isValidScopeType(String t) { return ScopeTypes.BPMN.equals(t) || ScopeTypes.CMMN.equals(t); }

try {
    jobQuery.scopeType(scopeType);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("scopeType was null", e);
}

When it happens

Trigger: Calling jobQuery.scopeType(null) directly, or via an or(...) block. Any code path that builds the scope type dynamically from a nullable config or enum lookup that resolved to null.

Common situations: Resolving scope type from a string config value that was missing; a switch/lookup returning null for an unknown scope name; generic query-builder code passing through unset fields.

Related errors

• text is null
• bytes array is null
• Deployment id is null
• Deployment ids is null
• deploymentName is null

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