What causes "status is null" in flowable/flowable-engine?

Pass a concrete status string (e.g. "pending", "failed") to status(...)

flowable/flowable-engine · error · FlowableIllegalArgumentException

status is null

Error message

status is null

What it means

BatchPartBuilderImpl.status(String) throws FlowableIllegalArgumentException when status is null. Status (e.g. pending/completed/failed) is a required field for a batch part and is validated eagerly at setter time.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/BatchPartBuilderImpl.java:74

        return this;
    }

    @Override
    public BatchPartBuilder searchKey(String searchKey) {
        this.searchKey = searchKey;
        return this;
    }

    @Override
    public BatchPartBuilder searchKey2(String searchKey2) {
        this.searchKey2 = searchKey2;
        return this;
    }

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

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

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

Pass a concrete status string (e.g. "pending", "failed") to status(...)
Default to an initial status constant instead of null when state is undetermined
Enumerate/map all possible states so no path yields null

Example fix

// before
builder.status(currentStatus);
// after
builder.status(currentStatus != null ? currentStatus : "pending");

Defensive patterns

Strategy: validation

Validate before calling

Objects.requireNonNull(status, "batch part status must not be null");
builder.status(status);

Type guard

boolean hasStatus = status instanceof String s && !s.isEmpty();

Try / catch

try {
    builder.status(status);
} catch (FlowableIllegalArgumentException e) {
    builder.status("pending"); // safe initial status
}

Prevention

Use an enum for statuses and map to string, never null
Initialize status to a well-known start value
Cover all state transitions in unit tests

When it happens

Trigger: Calling .status(null) on a BatchPartBuilder, typically when the status is computed from job state that is not yet resolved.

Common situations: Async handlers writing a batch part before the status is known; state-machine lookups returning null for unmapped states.

Related errors

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