What causes "scopeType is empty" in flowable/flowable-engine?

Pass a valid scope type such as ScopeTypes.BPMN ("bpmn") or ScopeTypes.CMMN ("cmmn").

flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeType is empty

Error message

scopeType is empty

What it means

InternalVariableInstanceQueryImpl.scopeType(String) requires a non-empty scope type (e.g. "bpmn", "cmmn", "task") because the persistence layer queries variables by scope type discriminator. An empty or null string cannot match any scope, so FlowableIllegalArgumentException("scopeType is empty") is thrown.

Solutions

Pass a valid scope type such as ScopeTypes.BPMN ("bpmn") or ScopeTypes.CMMN ("cmmn").
Validate the scopeType input before building the query and reject empties upstream.
If scopeType is optional in your flow, skip calling scopeType(...) rather than passing an empty string.

Example fix

// before
query.scopeType(scopeType == null ? "" : scopeType); // throws when null

// after
if (StringUtils.isNotEmpty(scopeType)) {
    query.scopeType(scopeType);
}

Defensive patterns

Strategy: validation

Validate before calling

if (scopeType == null || scopeType.isEmpty()) {
    throw new IllegalArgumentException("scopeType must be a non-empty value like \"bpmn\" or \"cmmn\"");
}

Try / catch

try {
    query.scopeType(scopeType);
} catch (FlowableIllegalArgumentException e) {
    // fall back to a default scope
    query.scopeType(ScopeTypes.BPMN);
}

Prevention

Use ScopeTypes constants instead of raw strings.
Validate config/request input for scope type at the boundary.
Skip optional scopeType calls rather than passing empty strings.

When it happens

Trigger: Calling query.scopeType("") or query.scopeType(null) — StringUtils.isEmpty check at InternalVariableInstanceQueryImpl.java:179 fires.

Common situations: Scope type passed from a config property, request parameter, or enum lookup that resolves to an empty string; forgetting to set a default scope type in a service wrapper.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/InternalVariableInstanceQueryImpl.java:179

        }

        this.subScopeIds = subScopeIds;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery withoutSubScopeId() {
        if (subScopeId != null) {
            throw new FlowableIllegalArgumentException("Cannot combine withoutSubScopeId() with subScopeId(String) in the same query");
        }
        this.withoutSubScopeId = true;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery scopeType(String scopeType) {
        if (StringUtils.isEmpty(scopeType)) {
            throw new FlowableIllegalArgumentException("scopeType is empty");
        }
        this.scopeType = scopeType;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery scopeTypes(Collection<String> scopeTypes) {
        this.scopeTypes = scopeTypes;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery name(String name) {
        if (StringUtils.isEmpty(name)) {
            throw new FlowableIllegalArgumentException("name is empty");
        }
        this.name = name;
        return this;

View on GitHub (pinned to d6d39ce1c6)