flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeType is null

Error message

scopeType is null

What it means

BatchPartQueryImpl.scopeType() throws FlowableIllegalArgumentException when the scopeType argument is null. scopeType (e.g. 'bpmn', 'cmmn') is validated non-null at setter time because it drives both filtering and the typed batch handling downstream.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchPartQueryImpl.java:166

            throw new FlowableIllegalArgumentException("scopeId is null");
        }
        this.scopeId = scopeId;
        return this;
    }

    @Override
    public BatchPartQuery subScopeId(String subScopeId) {
        if (subScopeId == null) {
            throw new FlowableIllegalArgumentException("subScopeId is null");
        }
        this.subScopeId = subScopeId;
        return this;
    }

    @Override
    public BatchPartQuery scopeType(String scopeType) {
        if (scopeType == null) {
            throw new FlowableIllegalArgumentException("scopeType is null");
        }
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public BatchPartQuery tenantId(String tenantId) {
        if (tenantId == null) {
            throw new FlowableIllegalArgumentException("tenantId is null");
        }
        this.tenantId = tenantId;
        return this;
    }

    @Override
    public BatchPartQuery tenantIdLike(String tenantIdLike) {
        if (tenantIdLike == null) {
            throw new FlowableIllegalArgumentException("tenantIdLike is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass a valid scope type constant such as ScopeTypes.BPMN or ScopeTypes.CMMN
  2. Only chain .scopeType(...) when the value is non-null
  3. Confirm the scope type is set on the configuration or entity it is read from

Example fix

// before
query.scopeType(config.getScopeType()); // may be null
// after
if (config.getScopeType() != null) {
    query.scopeType(config.getScopeType());
} else {
    query.scopeType(ScopeTypes.BPMN);
}
Defensive patterns

Strategy: validation

Validate before calling

if (scopeType == null) {
    scopeType = ScopeTypes.BPMN; // sensible default
}
query.scopeType(scopeType);

Type guard

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

Try / catch

try {
    query.scopeType(scopeType);
} catch (FlowableIllegalArgumentException e) {
    query.scopeType(ScopeTypes.BPMN);
}

Prevention

When it happens

Trigger: Calling batchPartQuery().scopeType(null), or deriving the scope type from a variable/config entry that is absent.

Common situations: Generic batch handling code that reads a scope-type config key with no default; passing EngineConfiguration scope types when the engine module is not installed.

Related errors

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