flowable/flowable-engine · error · FlowableIllegalArgumentException

subScopeId is null

Error message

subScopeId is null

What it means

BatchPartBuilderImpl.subScopeId(String) throws FlowableIllegalArgumentException when subScopeId is null. The sub-scope id identifies the sub-element (e.g. a specific job or plan item) within the scope and is required by the builder.

Source

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

            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");
        }
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public BatchPart create() {
        if (batch == null) {
            throw new FlowableIllegalArgumentException("batch has to be provided");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Provide the sub-scope element's id (e.g. job id) before building the batch part
2. Only call subScopeId(...) after verifying the referenced sub-element exists
3. If your use case has no sub-scope, check whether an alternate builder/API without that requirement exists

Example fix

// before
builder.subScopeId(jobId); // jobId may be null
// after
if (jobId != null) {
    builder.subScopeId(jobId);
} else {
    throw new IllegalStateException("Job not resolved; cannot create batch part");
}

Objects.requireNonNull(subScopeId, "subScopeId must be provided");
builder.subScopeId(subScopeId);

boolean hasSubScope = subScopeId instanceof String s && !s.isEmpty();

try {
    builder.subScopeId(subScopeId);
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalStateException("Sub-scope element missing for batch part", e);
}

When it happens

Trigger: Calling .subScopeId(null) on a BatchPartBuilder, e.g. when the sub-element id comes from an optional association that was not set.

Common situations: Timer/job handlers building batch parts where the job id is missing; modeling errors leaving a scope without its sub-scope element.

Related errors

• type is null
• status is null
• scopeId 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/3692114c9390a852. Report an issue: GitHub.