flowable/flowable-engine · error · FlowableIllegalArgumentException

Start user id is null

Error message

Start user id is null

What it means

PlanItemInstanceQueryImpl.planItemInstanceStartUserId(String) throws FlowableIllegalArgumentException with message "Start user id is null" when the supplied startUserId is null. Flowable treats null criteria values as programmer errors rather than 'no filter', so the caller must either supply a real user id or omit the criterion.

Solutions

1. Check the user id for null before building the query and skip the criterion if absent
2. Ensure the authenticated user is set (e.g. Authentication.setAuthenticatedUserId(userId)) before reading it
3. Validate the request parameter and return a client error instead of forwarding null
4. Catch FlowableIllegalArgumentException around query construction for untrusted inputs

Example fix

// before
query.planItemInstanceStartUserId(startUserId); // throws when null
// after
if (startUserId != null) {
    query.planItemInstanceStartUserId(startUserId);
}

if (startUserId != null && !startUserId.isEmpty()) {
    query.planItemInstanceStartUserId(startUserId);
}

boolean hasStartUser = startUserId != null;

try {
    query.planItemInstanceStartUserId(startUserId);
} catch (FlowableIllegalArgumentException e) {
    log.warn("startUserId was null, filter skipped");
}

When it happens

Trigger: Calling planItemInstanceStartUserId(null), or passing a user id variable sourced from an unauthenticated context, a missing authentication principal, or an unset request parameter.

Common situations: Security-context code where the current user id is null because no user is logged in; REST handlers that forward optional query params straight into the Flowable query; tests that forget to set the authenticated user via Authentication.setAuthenticatedUserId.

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/3656008725e68850. Report an issue: GitHub.

Appendix: source

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

            this.started = true;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery notStarted() {
        if (inOrStatement) {
            this.currentOrQueryObject.notStarted = true;
        } else {
            this.notStarted = true;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery planItemInstanceStartUserId(String startUserId) {
        if (startUserId == null) {
            throw new FlowableIllegalArgumentException("Start user id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.startUserId = startUserId;
        } else {
            this.startUserId = startUserId;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery planItemInstanceAssignee(String assignee) {
        if (assignee == null) {
            throw new FlowableIllegalArgumentException("assignee is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.assignee = assignee;
        } else {
            this.assignee = assignee;

View on GitHub (pinned to d6d39ce1c6)