What causes "batch has to be provided" in flowable/flowable-engine?

Obtain/create the Batch first, then call batch(batchPart) on the builder before create(): builder.batch(batchService.createBatchBuilder()...createBatch() or an existing batch).

flowable/flowable-engine · error · FlowableIllegalArgumentException

batch has to be provided

Error message

batch has to be provided

What it means

BatchPartBuilderImpl.create() assembles and persists a batch part, but the batch (BatchPartBuilder.batch(BatchPart)) was never called on the builder, so the field is null. Flowable throws FlowableIllegalArgumentException to fail fast rather than persist a part with no owning batch. The error surfaces immediately when you call create().

Source

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

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

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

    @Override
    public BatchPart create() {
        if (batch == null) {
            throw new FlowableIllegalArgumentException("batch has to be provided");
        }

        if (type == null) {
            throw new FlowableIllegalArgumentException("type has to be provided");
        }
        if (commandExecutor != null) {
            return commandExecutor.execute(commandContext -> createSafe());
        } else {
            return createSafe();
        }
    }

    protected BatchPart createSafe() {
        BatchPartEntityManager partEntityManager = batchServiceConfiguration.getBatchPartEntityManager();
        BatchPartEntity batchPart = partEntityManager.create();
        batchPart.setBatchId(batch.getId());
        batchPart.setBatchType(batch.getBatchType());
        batchPart.setBatchSearchKey(batch.getBatchSearchKey());

View on GitHub (pinned to d6d39ce1c6)

Solutions

Obtain/create the Batch first, then call batch(batchPart) on the builder before create(): builder.batch(batchService.createBatchBuilder()...createBatch() or an existing batch).
If you only have a batch id, look it up via batchService.createBatchQuery().batchId(id).singleResult() and pass the entity.
Verify the builder chain order — fluent calls can be reordered so batch(...) is not silently skipped.
Add a null-check/assert on the Batch reference before building the part.

Example fix

// before
BatchPart part = batchService.createBatchPartBuilder()
    .type("search")
    .create();
// after
Batch batch = batchService.createBatchBuilder()
    .type("search")
    .searchKey("k")
    .create();
BatchPart part = batchService.createBatchPartBuilder()
    .batch(batch)
    .type("search")
    .create();

Defensive patterns

Strategy: validation

Validate before calling

if (batch == null) {
    throw new IllegalStateException("Batch must be created before building a batch part");
}
BatchPart part = batchService.createBatchPartBuilder()
    .batch(batch)
    .type("search")
    .create();

Type guard

boolean hasBatch(org.flowable.batch.api.Batch b) {
    return b != null && b.getId() != null;
}

Try / catch

try {
    BatchPart part = builder.create();
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("batch has to be provided")) {
        throw new IllegalStateException("BatchPartBuilder.batch(...) was not called before create()", e);
    }
    throw e;
}

Prevention

Always start the builder chain by resolving or creating the Batch, then call batch(...) immediately.
Wrap builder construction in a helper method so callers cannot build parts without a batch.
Unit-test the builder chain to assert parts are always created with a non-null batch.

When it happens

Trigger: Calling BatchPartBuilder.create() without first invoking batch(BatchPart) on the builder obtained from batchServiceConfiguration.getBatchService().createBatchPartBuilder() (or the management API equivalent).

Common situations: Building a batch part programmatically where the batch was created in another scope and the reference was lost; copy-pasted builder chains where the batch(...) line was deleted; migration from APIs where the batch id string was passed directly to the builder.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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