flowable/flowable-engine · error · FlowableIllegalArgumentException

Root process instance id is null

Error message

Root process instance id is null

What it means

ExecutionQueryImpl.rootProcessInstanceId(String) throws FlowableIllegalArgumentException when the root process instance id is null. The root-id filter must be a concrete value to constrain the query to a process-instance tree. Fail-fast validation happens at query construction.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:329

        if (processInstanceIds == null) {
            throw new FlowableIllegalArgumentException("Set of process instance ids is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of process instance ids is empty");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceIds = processInstanceIds;
        } else {
            this.processInstanceIds = processInstanceIds;
        }
        return this;
    }

    @Override
    public ExecutionQueryImpl rootProcessInstanceId(String rootProcessInstanceId) {
        if (rootProcessInstanceId == null) {
            throw new FlowableIllegalArgumentException("Root process instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.rootProcessInstanceId = rootProcessInstanceId;
        } else {
            this.rootProcessInstanceId = rootProcessInstanceId;
        }
        return this;
    }

    @Override
    public ExecutionQuery processInstanceBusinessKey(String businessKey) {
        if (businessKey == null) {
            throw new FlowableIllegalArgumentException("Business key is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.businessKey = businessKey;
        } else {
            this.businessKey = businessKey;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Null-check the root id before constructing the query
2. Resolve the root instance id from the execution (historyService/runtimeService) and handle the not-found case
3. If the tree root is unknown, drop this filter or use processInstanceId instead
4. Catch FlowableIllegalArgumentException if null input is an accepted condition

Example fix

// before
ExecutionQuery query = runtimeService.createExecutionQuery().rootProcessInstanceId(rootId);
// after
ExecutionQuery query = runtimeService.createExecutionQuery();
if (rootId != null) {
    query.rootProcessInstanceId(rootId);
}

if (rootId == null) {
    throw new IllegalArgumentException("rootProcessInstanceId must not be null");
}

boolean hasRootId(String rootId) {
    return rootId != null && !rootId.isBlank();
}

try {
    ExecutionQuery q = runtimeService.createExecutionQuery().rootProcessInstanceId(rootId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Missing root process instance id: {}", e.getMessage());
}

When it happens

Trigger: Calling rootProcessInstanceId(null), typically when the root id comes from a parent-context lookup or an optional variable that was null.

Common situations: Child-process handling code where the root instance was already ended; copying query parameters from another execution whose root id was never set; misread variable in a delegate.

Related errors

• rootScopeIds is null or empty
• parentScopeId is null
• parentScopeIds is null or empty
• Process instance id is null
• Provided scope definitionid is null

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