flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeType is null

Error message

scopeType is null

What it means

BatchPartBuilderImpl.scopeType(String) throws FlowableIllegalArgumentException when scopeType is null. The scope type (e.g. bpmn, cmmn) tells the batch service which engine scope the part belongs to and is a mandatory field.

Source

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

            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");
        }

        if (type == null) {
            throw new FlowableIllegalArgumentException("type has to be provided");
        }
        if (commandExecutor != null) {
            return commandExecutor.execute(commandContext -> createSafe());
        } else {
            return createSafe();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the correct ScopeTypes constant (e.g. ScopeTypes.BPMN or ScopeTypes.CMMN) to scopeType(...)
2. Derive the scope type from the engine context with a guaranteed non-null fallback or explicit error earlier in the flow
3. Validate batch job configuration at startup so scopeType is never missing at runtime

Example fix

// before
builder.scopeType(scopeType); // may be null
// after
builder.scopeType(scopeType != null ? scopeType : ScopeTypes.BPMN);

Objects.requireNonNull(scopeType, "scopeType must not be null");
if (!ScopeTypes.BPMN.equals(scopeType) && !ScopeTypes.CMMN.equals(scopeType)) {
    throw new IllegalArgumentException("Unknown scopeType: " + scopeType);
}
builder.scopeType(scopeType);

boolean isValidScopeType = ScopeTypes.BPMN.equals(scopeType) || ScopeTypes.CMMN.equals(scopeType);

try {
    builder.scopeType(scopeType);
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalArgumentException("scopeType not resolved from engine context", e);
}

When it happens

Trigger: Calling .scopeType(null) on a BatchPartBuilder, usually when the scope type is derived from a variable or configuration that is unset.

Common situations: Generic batch handlers that operate across engines and fail to map the current context to a scope type string; misconfigured batch job definitions.

Related errors

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