flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided sub scope id is null

Error message

Provided sub scope id is null

What it means

This FlowableIllegalArgumentException is thrown by SuspendedJobQueryImpl.subScopeId() when the caller passes a null sub scope id. Sub scope ids identify nested scopes (e.g. a plan item within a case) and must be non-null to form a valid filter. The exception is raised at query-build time for fail-fast behavior.

Source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:278

            this.scopeIds = scopeIds;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl withoutScopeId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutScopeId = true;
        } else {
            this.withoutScopeId = true;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl subScopeId(String subScopeId) {
        if (subScopeId == null) {
            throw new FlowableIllegalArgumentException("Provided sub scope id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.subScopeId = subScopeId;
        } else {
            this.subScopeId = subScopeId;
        }
        return this;
    }
    
    @Override
    public SuspendedJobQueryImpl scopeType(String scopeType) {
        if (scopeType == null) {
            throw new FlowableIllegalArgumentException("Provided scope type is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.scopeType = scopeType;
        } else {
            this.scopeType = scopeType;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Only call subScopeId()/planItemInstanceId() when a real id exists
2. Resolve the plan item instance first and skip the filter if absent
3. Validate inputs before building the query
4. Refactor the query assembly to conditionally add filters

Example fix

// before
query.subScopeId(subScopeId); // may be null
// after
if (subScopeId != null) {
    query.subScopeId(subScopeId);
}

if (subScopeId != null) {
    query.subScopeId(subScopeId);
}

boolean hasSubScopeId = subScopeId != null && !subScopeId.isBlank();

try {
    query.subScopeId(subScopeId);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("sub scope id is null")) {
        // skip sub-scope filtering
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling suspendedJobQuery().subScopeId(null) directly, or via planItemInstanceId(null), which delegates to subScopeId().

Common situations: Plan item instance id not resolved before querying; passing a variable that is null when the job is not associated with a plan item; generic query builders that do not skip absent filters.

Related errors

• Provided scope id is null
• Provided case instance id is null
• Provided case definition id is null
• Provided case definition key is null
• Deployment id is null

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