flowable/flowable-engine · error · FlowableIllegalArgumentException

parentScopeId is null

Error message

parentScopeId is null

What it means

Flowable's CaseInstanceQueryImpl throws FlowableIllegalArgumentException when caseInstanceParentScopeId(String) is called with null. A parent scope id filters case instances whose parent (e.g. a containing plan item or process scope) has the given id; null is not a meaningful filter value, so the API rejects it eagerly. Use a dedicated 'no parent' query path if that is the intent.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/CaseInstanceQueryImpl.java:399

    }

    @Override
    public CaseInstanceQuery caseInstanceRootScopeIds(Set<String> rootScopeIds) {
        if (rootScopeIds == null || rootScopeIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("rootScopeIds is null or empty");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.rootScopeIds = rootScopeIds;
        } else {
            this.rootScopeIds = rootScopeIds;
        }
        return this;
    }

    @Override
    public CaseInstanceQuery caseInstanceParentScopeId(String parentScopeId) {
        if (parentScopeId == null) {
            throw new FlowableIllegalArgumentException("parentScopeId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeId = parentScopeId;
        } else {
            this.parentScopeId = parentScopeId;
        }
        return this;
    }

    @Override
    public CaseInstanceQuery caseInstanceParentScopeIds(Set<String> parentScopeIds) {
        if (parentScopeIds == null || parentScopeIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("parentScopeIds is null or empty");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentScopeIds = parentScopeIds;
        } else {
            this.parentScopeIds = parentScopeIds;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the parent scope id lookup actually returns a value before building the query; only add the criterion when the id is non-null
2. Confirm you are passing the correct scope id (parent scope of the case instance, not the case instance id itself)
3. If 'any parent' is intended, omit the parentScopeId criterion entirely
4. If 'no parent' is intended, use caseInstanceWithoutParentScopeId / the appropriate no-parent API instead of null

Example fix

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

if (parentScopeId == null || parentScopeId.isBlank()) {
    throw new IllegalArgumentException("parentScopeId must be provided");
}
query.caseInstanceParentScopeId(parentScopeId);

boolean hasText(String s) {
    return s != null && !s.trim().isEmpty();
}

try {
    query.caseInstanceParentScopeId(parentScopeId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("parentScopeId was null: {}", e.getMessage());
    query = runtimeService.createCaseInstanceQuery(); // rebuild without the filter
}

When it happens

Trigger: Calling caseInstanceParentScopeId(null) directly, or passing a variable holding the parent scope id that was never populated (lookup of the parent plan item/execution returned null).

Common situations: Resolving a parent scope from a runtime activity/plan-item that has already completed or not yet started; misreading which id to pass (passing case instance id vs scope id); dynamic query builders that forward nullable request parameters unfiltered.

Related errors

• rootScopeIds is null or empty
• parentScopeIds is null or empty
• caseInstanceId is null
• variable name is null
• caseInstanceId is null

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