flowable/flowable-engine · error · FlowableIllegalArgumentException

scopeId is empty

Error message

scopeId is empty

What it means

InternalVariableInstanceQueryImpl.scopeId(String) throws FlowableIllegalArgumentException when the given scopeId is null or empty. Scope-scoped variables (e.g. CMMN case or other scoped storage) require a concrete scope identifier, so blank input is rejected eagerly before query execution.

Solutions

1. Resolve a valid non-empty scope id before building the query
2. Short-circuit and return an empty result when no scope id is available
3. Validate the scope id at your API boundary

Example fix

// before
query.scopeId(scopeId); // throws when blank
// after
if (scopeId != null && !scopeId.isEmpty()) {
    query.scopeId(scopeId);
} else {
    return Collections.emptyList();
}

if (scopeId == null || scopeId.isEmpty()) { throw new IllegalArgumentException("scopeId required"); }

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

try { query.scopeId(scopeId); } catch (FlowableIllegalArgumentException e) { log.warn("Missing scopeId for variable query", e); return Collections.emptyList(); }

When it happens

Trigger: Calling scopeId(null) or scopeId("") — e.g. a scope id variable not yet initialized, an id read from an empty payload field, or querying outside any scope.

Common situations: Case/task scope id sourced from a request body not yet populated; code invoked before the scoped entity is created; passing the wrong variable that happens to be empty.

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

• executionId is empty
• None of the given process categories can be null
• processInstanceId is empty
• Task id list is null
• Task name list is null

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

Appendix: source

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

            throw new FlowableIllegalArgumentException("executionIds is null or empty");
        }
        this.executionIds = executionIds;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery withoutTaskId() {
        if (taskId != null || taskIds != null) {
            throw new FlowableIllegalArgumentException("Cannot combine withoutTaskId() with task(String) or taskIds(Collection) in the same query");
        }
        this.withoutTaskId = true;
        return this;
    }

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

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

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

        if (withoutSubScopeId) {

View on GitHub (pinned to d6d39ce1c6)