flowable/flowable-engine · error · FlowableIllegalArgumentException

endedBefore is null

Error message

endedBefore is null

What it means

Flowable throws FlowableIllegalArgumentException when planItemInstanceEndedBefore(Date) receives a null Date. Eager argument validation ensures invalid queries fail immediately at build time rather than producing bad SQL or misleading results. An absent end-date filter should be expressed by omitting the method call.

Solutions

1. Provide a validated non-null Date.
2. Skip the method call when no endedBefore filter applies.
3. Parse/validate date strings before constructing the query.
4. Catch FlowableIllegalArgumentException around query building to convert it into a user-facing validation error.

Example fix

// before
query.planItemInstanceEndedBefore(filter.getEndedBefore()); // may be null
// after
if (filter.getEndedBefore() != null) {
    query.planItemInstanceEndedBefore(filter.getEndedBefore());
}

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

boolean hasEndedBefore = (endedBefore != null);

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

When it happens

Trigger: Calling createPlanItemInstanceQuery().planItemInstanceEndedBefore(null), typically when the ended-before timestamp originates from an optional parameter that was never set.

Common situations: Missing 'endedBefore' value in a report/filter request; JSON payload omitting the field; null from a failed date parse of user input.

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/83c123346cca46d7. Report an issue: GitHub.

Appendix: source

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

    }

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

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

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

View on GitHub (pinned to d6d39ce1c6)