flowable/flowable-engine · error · FlowableIllegalArgumentException

rootScopeId is null

Error message

rootScopeId is null

What it means

Flowable throws FlowableIllegalArgumentException from CaseInstanceQueryImpl.caseInstanceRootScopeId(String) when the root scope id is null. The root scope id identifies the top-level scope (case or process) and null is never a valid filter, so it is rejected during query construction. Skip the method call when the id is unknown.

Solutions

1. Guard the call: if (rootScopeId != null) query.caseInstanceRootScopeId(rootScopeId)
2. Verify the source of the root scope id — if it should exist but is null, fix the upstream lookup or data
3. Use caseInstanceId or caseInstanceParentId as alternative criteria when root scope is unavailable
4. Catch FlowableIllegalArgumentException around query building for graceful API error handling

Example fix

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

if (rootScopeId != null) { query.caseInstanceRootScopeId(rootScopeId); }

boolean hasRootScope = rsId instanceof String s && !s.isBlank();

try { query.caseInstanceRootScopeId(rootScopeId); } catch (FlowableIllegalArgumentException e) { log.warn("Null rootScopeId supplied to case instance query"); throw new BadRequestException(e.getMessage()); }

When it happens

Trigger: Calling createCaseInstanceQuery().caseInstanceRootScopeId(null), usually because the root scope id came from a lookup on an entity that has no root scope, or from an unset/missing parameter.

Common situations: Navigation from child entities (plan items, tasks) whose rootScopeId was not populated; API endpoints with optional root-scope filters; data from older Flowable versions before rootScopeId existed.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

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

    }

    @Override
    public CaseInstanceQuery caseInstanceNameLikeIgnoreCase(String nameLikeIgnoreCase) {
        if (nameLikeIgnoreCase == null) {
            throw new FlowableIllegalArgumentException("Name like ignore case is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.nameLikeIgnoreCase = nameLikeIgnoreCase;
        } else {
            this.nameLikeIgnoreCase = nameLikeIgnoreCase;
        }
        return this;
    }

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

View on GitHub (pinned to d6d39ce1c6)