flowable/flowable-engine · error · FlowableIllegalArgumentException

status is null

Error message

status is null

What it means

BatchPartQueryImpl.status() throws FlowableIllegalArgumentException when the status filter value is null. The Flowable query API validates each fluent setter argument eagerly so that invalid queries fail at construction time instead of producing broken SQL at listPage()/singleResult() time. A null status cannot be matched against the batch part STATUS_ column, so it is rejected outright.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchPartQueryImpl.java:139

            throw new FlowableIllegalArgumentException("batchSearchKey is null");
        }
        this.batchSearchKey = searchKey;
        return this;
    }

    @Override
    public BatchPartQuery batchSearchKey2(String searchKey2) {
        if (searchKey2 == null) {
            throw new FlowableIllegalArgumentException("batchSearchKey2 is null");
        }
        this.batchSearchKey2 = searchKey2;
        return this;
    }

    @Override
    public BatchPartQuery status(String status) {
        if (status == null) {
            throw new FlowableIllegalArgumentException("status is null");
        }
        this.status = status;
        return this;
    }

    @Override
    public BatchPartQuery scopeId(String scopeId) {
        if (scopeId == null) {
            throw new FlowableIllegalArgumentException("scopeId is null");
        }
        this.scopeId = scopeId;
        return this;
    }

    @Override
    public BatchPartQuery subScopeId(String subScopeId) {
        if (subScopeId == null) {
            throw new FlowableIllegalArgumentException("subScopeId is null");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass a non-null status string, e.g. 'ready' or 'failed', matching values stored in FLW_EV_BATCH_PART.STATUS_
  2. Guard the call: only invoke .status(...) when the value is non-null
  3. If you intended no filter, simply omit the .status(...) call instead of passing null

Example fix

// before
query.status(myStatus); // myStatus may be null
// after
if (myStatus != null) {
    query.status(myStatus);
}
Defensive patterns

Strategy: validation

Validate before calling

if (status == null) {
    throw new IllegalArgumentException("status must be non-null before calling BatchPartQuery.status()");
}
query.status(status);

Type guard

boolean hasStatus(String s) { return s != null && !s.isEmpty(); }

Try / catch

try {
    query.status(status);
} catch (FlowableIllegalArgumentException e) {
    // fall back to unfiltered query or rethrow with context
}

Prevention

When it happens

Trigger: Calling batchPartQuery().status(null) directly, or passing a variable/field that is null (e.g. status resolved from a request parameter or enum lookup that returned null).

Common situations: REST/API layers binding an optional 'status' query parameter into the Flowable query without a null check; refactors where a status constant was removed or renamed leaving the lookup null.

Related errors

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