flowable/flowable-engine · error · FlowableIllegalArgumentException

subScopeId is empty

Error message

subScopeId is empty

What it means

InternalVariableInstanceQueryImpl.subScopeId(String) throws FlowableIllegalArgumentException when the given subScopeId is null or empty, and additionally when withoutSubScopeId was already set on the same query. A concrete sub-scope id and 'no sub-scope' are mutually exclusive filters, and blank input is always invalid.

Solutions

1. Pass a valid non-empty subScopeId and ensure withoutSubScopeId() is not called on the same query
2. Use either subScopeId(...) or withoutSubScopeId(), not both
3. Guard the call site for null/empty before building

Example fix

// before
query.withoutSubScopeId();
query.subScopeId(subScopeId); // throws
// after
if (subScopeId != null && !subScopeId.isEmpty()) {
    query.subScopeId(subScopeId);
} else {
    query.withoutSubScopeId();
}

if (subScopeId == null || subScopeId.isEmpty()) { throw new IllegalArgumentException("subScopeId required"); } if (useWithoutSubScopeId) { throw new IllegalStateException("subScopeId and withoutSubScopeId are mutually exclusive"); }

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

try { query.subScopeId(subScopeId); } catch (FlowableIllegalArgumentException e) { throw new QueryConfigurationException(e.getMessage(), e); }

When it happens

Trigger: Calling subScopeId(null) or subScopeId(""); or calling subScopeId(x) after withoutSubScopeId() on the same builder instance.

Common situations: Sub-scope id taken from an uninitialized variable; filter assembly that sets withoutSubScopeId earlier and later also sets a concrete id; shared query builders mutated by multiple code paths.

Related errors

• Cannot combine taskId(String) with withoutTaskId() in the…
• Cannot combine taskIds(Collection) with withoutTaskId() in…
• Cannot combine withoutTaskId() with task(String) or…
• Cannot use taskIds together with excludeLocalVariables
• executionId is empty

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

Appendix: source

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

    @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) {
            throw new FlowableIllegalArgumentException("Cannot combine subScopeId(String) with withoutSubScopeId() in the same query");
        }

        this.subScopeId = subScopeId;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery subScopeIds(Collection<String> subScopeIds) {
        if (withoutSubScopeId) {
            throw new FlowableIllegalArgumentException("Cannot combine subScopeIds with withoutSubScopeId in the same query");
        }

        this.subScopeIds = subScopeIds;
        return this;

View on GitHub (pinned to d6d39ce1c6)