What causes "before time is null" in flowable/flowable-engine?

Pass a valid java.util.Date (e.g. new Date() or a parsed value)

flowable/flowable-engine · error · FlowableIllegalArgumentException

before time is null

Error message

before time is null

What it means

Flowable throws this FlowableIllegalArgumentException when CaseInstanceQueryImpl.caseInstanceStartedBefore(Date) receives a null beforeTime. The started-before filter bounds the query's start-time comparison in SQL; a null bound is ambiguous and rejected at query-construction time.

Source

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

    }

    @Override
    public CaseInstanceQueryImpl caseInstanceParentId(String parentId) {
        if (parentId == null) {
            throw new FlowableIllegalArgumentException("Parent id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.caseInstanceParentId = parentId;
        } else {
            this.caseInstanceParentId = parentId;
        }
        return this;
    }

    @Override
    public CaseInstanceQueryImpl caseInstanceStartedBefore(Date beforeTime) {
        if (beforeTime == null) {
            throw new FlowableIllegalArgumentException("before time is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.startedBefore = beforeTime;
        } else {
            this.startedBefore = beforeTime;
        }
        return this;
    }

    @Override
    public CaseInstanceQueryImpl caseInstanceStartedAfter(Date afterTime) {
        if (afterTime == null) {
            throw new FlowableIllegalArgumentException("after time is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.startedAfter = afterTime;
        } else {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass a valid java.util.Date (e.g. new Date() or a parsed value)
Omit the startedBefore filter when no upper bound is desired
Null-check the parsed date before applying the filter

Example fix

// before
query.caseInstanceStartedBefore(parseDate(beforeStr)); // parseDate may return null
// after
Date before = parseDate(beforeStr);
if (before != null) {
    query.caseInstanceStartedBefore(before);
}

Defensive patterns

Strategy: validation

Validate before calling

Date before = parseDate(beforeStr);
if (before != null) {
    query.caseInstanceStartedBefore(before);
}

Type guard

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

Try / catch

try {
    query.caseInstanceStartedBefore(before);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Skipping started-before filter: {}", e.getMessage());
}

Prevention

Return Optional<Date> from date parsers instead of null
Make optional date filters conditional in the query builder chain
Use java.time types internally and convert to Date at the last moment

When it happens

Trigger: Calling caseInstanceQuery.caseInstanceStartedBefore(null) directly, or passing a Date parsed from user input/REST parameter that failed to parse or was absent.

Common situations: Date-range search UIs where the 'before' field is optional; converting a null String date via a formatter that returns null; timezone/parse failures yielding a null Date.

Related errors

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