flowable/flowable-engine · error · FlowableIllegalArgumentException

subScopeId is null

Error message

subScopeId is null

What it means

BatchPartQueryImpl.subScopeId() throws FlowableIllegalArgumentException when the subScopeId argument is null. The setter validates non-null because subScopeId is used as an equality filter on the SUB_SCOPE_ID_ column and null would be ambiguous.

Source

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

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

    @Override
    public BatchPartQuery scopeId(String scopeId) {
        if (scopeId == null) {
            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");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass a non-null subScopeId string
  2. Omit the .subScopeId(...) call when sub-scope filtering is not needed
  3. Check the source object for a populated subScopeId before chaining the filter

Example fix

// before
query.subScopeId(part.getSubScopeId()); // may be null
// after
if (part.getSubScopeId() != null) {
    query.subScopeId(part.getSubScopeId());
}
Defensive patterns

Strategy: validation

Validate before calling

if (subScopeId == null) {
    throw new IllegalArgumentException("subScopeId must be non-null before calling BatchPartQuery.subScopeId()");
}
query.subScopeId(subScopeId);

Type guard

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

Try / catch

try {
    query.subScopeId(subScopeId);
} catch (FlowableIllegalArgumentException e) {
    // degrade to scope-only query
    query.scopeId(scopeId);
}

Prevention

When it happens

Trigger: Calling batchPartQuery().subScopeId(null), or passing a subScopeId extracted from a variable/DTO that was never populated.

Common situations: Querying batch parts for a sub-scope that does not exist; copying scope/subScope values from a partially initialized entity.

Related errors

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