flowable/flowable-engine · error · FlowableIllegalArgumentException

failedBefore is null

Error message

failedBefore is null

What it means

Flowable throws FlowableIllegalArgumentException when planItemInstanceFailedBefore(Date) receives a null Date. This eager argument check ensures the query only ever contains usable timestamp criteria. Null means 'no filter', which the API expresses by not calling the method.

Solutions

1. Supply a validated non-null Date.
2. Apply the criterion only when the value exists.
3. Reject empty or unparseable date strings before building the query.
4. Use try-catch on FlowableIllegalArgumentException to fail fast with a clear message.

Example fix

// before
query.planItemInstanceFailedBefore(searchCriteria.getFailedBefore()); // may be null
// after
Date failedBefore = searchCriteria.getFailedBefore();
if (failedBefore != null) {
    query.planItemInstanceFailedBefore(failedBefore);
}

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

boolean hasFailedBefore = (failedBefore != null);

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

When it happens

Trigger: Calling createPlanItemInstanceQuery().planItemInstanceFailedBefore(null), e.g. when the failed-before date originates from an optional client-supplied filter.

Common situations: Search form where 'failedBefore' was left blank; missing field after payload deserialization; date-parsing utility returning null for bad 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/d7a9d8e0df79b6ae. Report an issue: GitHub.

Appendix: source

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

    }

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

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

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

View on GitHub (pinned to d6d39ce1c6)