flowable/flowable-engine · error · FlowableIllegalArgumentException

occurredAfter is null

Error message

occurredAfter is null

What it means

Flowable throws FlowableIllegalArgumentException when planItemInstanceOccurredAfter(Date) is given a null Date argument. This eager validation prevents building a query with an unusable timestamp criterion. To leave the criterion unset, simply do not invoke the method.

Solutions

1. Resolve a valid non-null Date before calling the method.
2. Conditionally apply the criterion only when the value is present.
3. Validate/parse user-supplied date strings before constructing the query.
4. Catch FlowableIllegalArgumentException during query building and return a client validation error.

Example fix

// before
query.planItemInstanceOccurredAfter(toDate(request.getOccurredAfter())); // toDate may return null
// after
Date occurredAfter = toDate(request.getOccurredAfter());
if (occurredAfter != null) {
    query.planItemInstanceOccurredAfter(occurredAfter);
}

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

boolean hasOccurredAfter = (occurredAfter != null);

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

When it happens

Trigger: Calling createPlanItemInstanceQuery().planItemInstanceOccurredAfter(null), commonly when the after-date comes from an optional API parameter that was not supplied.

Common situations: Missing 'occurredAfter' query parameter in a REST endpoint; JSON payload omitting the field; a date formatter returning null on unparseable 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/c4c5930dfa6e9420. Report an issue: GitHub.

Appendix: source

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

    }

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

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

View on GitHub (pinned to d6d39ce1c6)