flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeId is null

Error message

scopeId is null

What it means

BatchPartQueryImpl.scopeId() throws FlowableIllegalArgumentException when the scopeId argument is null. Flowable validates the argument at setter time because a null scope id is meaningless as a filter on the batch part SCOPE_ID_ column. The query builder fails fast rather than at query execution.

Source

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass a valid non-null scope id string
  2. Skip the .scopeId(...) call when the value is null if filtering by scope is optional
  3. Verify the entity you derived the scopeId from actually has a scope set

Example fix

// before
query.scopeId(execution.getScopeId()); // may be null
// after
String scopeId = execution.getScopeId();
if (scopeId != null) {
    query.scopeId(scopeId);
}
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

try {
    query.scopeId(scopeId);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("scopeId was null, skipping scope filter");
}

Prevention

When it happens

Trigger: Calling batchPartQuery().scopeId(null), or forwarding a scopeId obtained from a process/execution context that is null (e.g. a batch part with no scope).

Common situations: Building a batch part query from a callback where scope info was not propagated; passing result of execution.getScopeId() for a non-scoped execution.

Related errors

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