flowable/flowable-engine · error · FlowableIllegalArgumentException

Involved user is null

Error message

Involved user is null

What it means

Flowable's ProcessInstanceQuery.involvedUser(String) throws FlowableIllegalArgumentException when the involvedUser argument is null. The involvement filter on process instances requires a concrete user id; a null value cannot be translated into a database condition. The check fails fast during query construction.

Solutions

1. Null-check the user id before building the query and skip the involvedUser filter when absent.
2. Resolve the current user only when authenticated, and require a non-null user before invoking involvement queries.
3. Validate at the API boundary (e.g. @NotNull on the request parameter) so null never reaches the Flowable query.
4. Catch FlowableIllegalArgumentException around query construction and return a 400-style validation error.

Example fix

// before
String user = securityService.getCurrentUser(); // may be null
runtimeService.createProcessInstanceQuery().involvedUser(user);
// after
String user = securityService.getCurrentUser();
if (user != null) {
    runtimeService.createProcessInstanceQuery().involvedUser(user);
}

if (userId == null || userId.isBlank()) { throw new BadRequestException("involvedUser is required"); }
runtimeService.createProcessInstanceQuery().involvedUser(userId);

boolean isPresentUser(String u) { return u != null && !u.isBlank(); }

try {
    query.involvedUser(userId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("involvedUser was null: {}", e.getMessage());
    throw new BadRequestException("involvedUser must not be null");
}

When it happens

Trigger: Calling processInstanceQuery().involvedUser(null), typically when the user id comes from a request parameter, security context (anonymous/unauthenticated user), or a lookup that returned null.

Common situations: Web controllers passing request parameters straight into queries; authenticated-user helpers returning null for anonymous sessions; integration code where the user record was deleted but still referenced.

Related errors

• Set of process definition keys is null
• activatedBefore is null
• activity tenant id is null
• after time is null
• Assignee is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:573

            this.subProcessInstanceId = subProcessInstanceId;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery excludeSubprocesses(boolean excludeSubprocesses) {
        if (inOrStatement) {
            this.currentOrQueryObject.excludeSubprocesses = excludeSubprocesses;
        } else {
            this.excludeSubprocesses = excludeSubprocesses;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery involvedUser(String involvedUser) {
        if (involvedUser == null) {
            throw new FlowableIllegalArgumentException("Involved user is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.involvedUser = involvedUser;
        } else {
            this.involvedUser = involvedUser;
        }
        return this;
    }
    
    @Override
    public ProcessInstanceQuery involvedUser(String userId, String identityLinkType) {
        if (userId == null) {
            throw new FlowableIllegalArgumentException("userId is null");
        }
        if (identityLinkType == null) {
            throw new FlowableIllegalArgumentException("identityLinkType is null");
        }

View on GitHub (pinned to d6d39ce1c6)