What causes "Provided date is null" in flowable/flowable-engine?

Pass a non-null Date; if the filter is optional, skip calling duedateHigherThan entirely when the date is null.

flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided date is null

Error message

Provided date is null

What it means

duedateHigherThan(Date) filters suspended jobs whose due date is after the given date. The library throws FlowableIllegalArgumentException when the argument is null because a null date cannot express a comparison boundary and would silently corrupt the query. This guard rejects the bad input immediately at builder time.

Solutions

Pass a non-null Date; if the filter is optional, skip calling duedateHigherThan entirely when the date is null.
Default the date to a sensible value (e.g. new Date(0) or start of day) before building the query.
Fix the upstream parsing/assignment that left the Date null.

Example fix

// before
query.duedateHigherThan(optionalDate); // optionalDate may be null
// after
if (optionalDate != null) {
    query.duedateHigherThan(optionalDate);
}

Defensive patterns

Strategy: validation

Validate before calling

if (date == null) {
    throw new IllegalArgumentException("duedateHigherThan requires a non-null date");
}

Type guard

boolean isApplicable(Date d) { return d != null; }

Try / catch

try {
    query.duedateHigherThan(date);
} catch (FlowableIllegalArgumentException e) {
    // omit the optional date filter or supply a default
    query.duedateHigherThan(new Date(0));
}

Prevention

Use Optional<Date> for optional bounds and only apply the filter when present.
Never pass Date values straight from nullable DTO/config fields into the query builder.
Check date-parsing helpers for null-on-failure behavior before using their result.

When it happens

Trigger: Calling suspendedJobQuery().duedateHigherThan(someDate) where someDate is null — e.g. a Date field/variable that was never assigned, or an optional request parameter that was not defaulted.

Common situations: Passing a parsed date that failed to parse, reading a nullable config/DTO field for the 'due after' window, or Java deserialization leaving the Date null. Also happens with method-chaining on a value returned by a map lookup.

Related errors

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

Appendix: source

Thrown at modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java:495

            throw new FlowableIllegalArgumentException("Cannot combine onlyMessages() with onlyExternalWorkers() in the same query");
        }

        if (onlyTimers) {
            throw new FlowableIllegalArgumentException("Cannot combine onlyTimers() with onlyExternalWorkers() in the same query");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.onlyExternalWorkers = true;
        } else {
            this.onlyExternalWorkers = true;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl duedateHigherThan(Date date) {
        if (date == null) {
            throw new FlowableIllegalArgumentException("Provided date is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.duedateHigherThan = date;
        } else {
            this.duedateHigherThan = date;
        }
        return this;
    }

    @Override
    public SuspendedJobQueryImpl duedateLowerThan(Date date) {
        if (date == null) {
            throw new FlowableIllegalArgumentException("Provided date is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.duedateLowerThan = date;
        } else {
            this.duedateLowerThan = date;

View on GitHub (pinned to d6d39ce1c6)