flowable/flowable-engine · error · FlowableIllegalArgumentException

rootScopeId is null

Error message

rootScopeId is null

What it means

caseInstanceRootScopeId(String) throws FlowableIllegalArgumentException('rootScopeId is null') when the root scope id argument is null. The root-scope filter identifies the top-level scope of a case hierarchy and must be a concrete id.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:409

    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceBusinessKeyLikeIgnoreCase(String businessKeyLikeIgnoreCase) {
        if (businessKeyLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        } else {
            this.businessKeyLikeIgnoreCase = businessKeyLikeIgnoreCase;
        }
        return this;
    }
    
    @Override
    public HistoricCaseInstanceQueryImpl caseInstanceRootScopeId(String rootScopeId) {
        if (rootScopeId == null) {
            throw new FlowableIllegalArgumentException("rootScopeId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.rootScopeId = rootScopeId;
        } else {
            this.rootScopeId = rootScopeId;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQuery 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;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve and pass a valid root scope id (e.g. the case instance's root scope id).
2. Skip the setter when the root id is unknown so the filter is not applied.
3. Catch FlowableIllegalArgumentException and handle as invalid query input.

Example fix

// before
query.caseInstanceRootScopeId(parent.getRootScopeId()); // parent may be null
// after
if (parent != null && parent.getRootScopeId() != null) {
    query.caseInstanceRootScopeId(parent.getRootScopeId());
}

if (rootScopeId == null) { throw new IllegalArgumentException("rootScopeId must not be null"); }
historicCaseInstanceQuery.caseInstanceRootScopeId(rootScopeId);

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

try {
    query.caseInstanceRootScopeId(rootScopeId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("rootScopeId is required", e);
}

When it happens

Trigger: Calling caseInstanceRootScopeId(null), e.g. when the parent/root id was not resolved before querying.

Common situations: Hierarchical case queries where the root id comes from a parent entity that is missing or was not loaded; REST filters wired to optional params.

Related errors

• Case definition version is null
• Case instance id is null
• Case instance ids is null
• Business key is null
• rootScopeIds is null or empty

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