flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeId is null

Error message

scopeId is null

What it means

BatchPartBuilderImpl.scopeId(String) throws FlowableIllegalArgumentException when scopeId is null. The scope id links the batch part to the scope (e.g. process/case/task instance) it operates on and is a required field.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/BatchPartBuilderImpl.java:83

    @Override
    public BatchPartBuilder searchKey2(String searchKey2) {
        this.searchKey2 = searchKey2;
        return this;
    }

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

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve and pass a valid scope id (process instance / case / task id) before building the batch part
2. Skip building the part when the target instance id cannot be resolved, and log/skip instead
3. Check upstream lookups (runtimeService.create...Query) that may have returned null

Example fix

// before
builder.scopeId(possiblyNullId);
// after
if (possiblyNullId == null) {
    throw new IllegalStateException("Scope id must be resolved before creating a batch part");
}
builder.scopeId(possiblyNullId);

Objects.requireNonNull(scopeId, "scopeId must be resolved before creating a batch part");
builder.scopeId(scopeId);

boolean hasScope = scopeId instanceof String s && !s.isEmpty();

try {
    builder.scopeId(scopeId);
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalStateException("Cannot create batch part: target scope id not resolved", e);
}

When it happens

Trigger: Calling .scopeId(null) while building a batch part, e.g. when the execution/entity id variable is null because the target instance was not resolved.

Common situations: Bulk operations iterating over instances where some ids failed to resolve; passing execution.getId() from a detached or already-ended execution.

Related errors

• type is null
• status is null
• subScopeId is null
• scopeType is null
• Must specify a process definition id to migrate

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