flowable/flowable-engine · error · FlowableIllegalArgumentException

occurredBefore is null

Error message

occurredBefore is null

What it means

Flowable throws FlowableIllegalArgumentException when planItemInstanceOccurredBefore(Date) receives a null Date. Query criteria methods validate arguments eagerly so invalid queries fail at build time instead of at SQL execution. A null filter value should be expressed by not calling the method at all.

Solutions

1. Provide a concrete Date before calling planItemInstanceOccurredBefore.
2. Guard the call site with a null check and skip the method when the value is absent.
3. Parse string inputs explicitly and reject empty/invalid values before query construction.
4. Catch FlowableIllegalArgumentException around query building to surface a meaningful validation error.

Example fix

// before
query.planItemInstanceOccurredBefore(input.getOccurredBefore()); // null when unset
// after
if (input.getOccurredBefore() != null) {
    query.planItemInstanceOccurredBefore(input.getOccurredBefore());
}

if (occurredBefore == null) {
    throw new IllegalArgumentException("occurredBefore must be non-null; omit the filter instead");
}
query.planItemInstanceOccurredBefore(occurredBefore);

boolean hasOccurredBefore = (occurredBefore != null);

try {
    query.planItemInstanceOccurredBefore(occurredBefore);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("occurredBefore")) {
        throw new BadRequestException("occurredBefore date filter must not be null");
    }
    throw e;
}

When it happens

Trigger: Calling createPlanItemInstanceQuery().planItemInstanceOccurredBefore(null), e.g. when the before-date originates from an optional client parameter or an unset DTO field.

Common situations: Web layer forwarding a missing 'occurredBefore' request parameter; deserialization leaving the field null; a failed date conversion returning null.

Related errors

• activatedBefore is null
• activity tenant id is null
• after time is null
• category is null
• categoryLike is null

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

Appendix: source

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

    }

    @Override
    public PlanItemInstanceQuery planItemInstanceCompletedAfter(Date completedAfter) {
        if (completedAfter == null) {
            throw new FlowableIllegalArgumentException("completedAfter is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.completedAfter = completedAfter;
        } else {
            this.completedAfter = completedAfter;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery planItemInstanceOccurredBefore(Date occurredBefore) {
        if (occurredBefore == null) {
            throw new FlowableIllegalArgumentException("occurredBefore is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.occurredBefore = occurredBefore;
        } else {
            this.occurredBefore = occurredBefore;
        }
        return this;
    }

    @Override
    public PlanItemInstanceQuery planItemInstanceOccurredAfter(Date occurredAfter) {
        if (occurredAfter == null) {
            throw new FlowableIllegalArgumentException("occurredAfter is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.occurredAfter = occurredAfter;
        } else {
            this.occurredAfter = occurredAfter;

View on GitHub (pinned to d6d39ce1c6)