flowable/flowable-engine · error · FlowableIllegalArgumentException

completedBy is null

Error message

completedBy is null

What it means

PlanItemInstanceQueryImpl.planItemInstanceCompletedBy(String) throws FlowableIllegalArgumentException with message "completedBy is null" when the completedBy argument is null. Flowable's query setters fail fast on null since a null criterion cannot be expressed in the generated where-clause.

Solutions

1. Null-check the completedBy value and add the criterion only when present
2. Restrict the query to completed instances before filtering by completedBy if completeness is expected
3. Handle missing JSON/DTO fields with defaults or explicit validation upstream
4. Catch FlowableIllegalArgumentException around dynamic query construction

Example fix

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

if (completedBy != null) {
    query.planItemInstanceCompletedBy(completedBy);
}

boolean hasCompleter = completedBy != null;

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

When it happens

Trigger: Calling planItemInstanceCompletedBy(null), typically when the completing user is unknown (plan item not yet completed) or comes from a nullable source.

Common situations: Reporting screens that read completedBy from active (never-completed) plan item instances; copying a field from one entity to a query without a null check; deserialized JSON payloads with a missing completedBy key.

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/30a199daabf246d3. Report an issue: GitHub.

Appendix: source

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

    }

    @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;
        }
        return this;
    }

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

    @Override
    public PlanItemInstanceQuery planItemInstanceReferenceId(String referenceId) {
        if (inOrStatement) {
            this.currentOrQueryObject.referenceId = referenceId;
        } else {
            this.referenceId = referenceId;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)