flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided batch id is null

Error message

Provided batch id is null

What it means

BatchQueryImpl.batchId() throws FlowableIllegalArgumentException with message 'Provided batch id is null' when the id argument is null. The batch query validates each filter at setter time so that queries with missing mandatory identifiers fail immediately rather than returning unintended full-table results.

Source

Thrown at modules/flowable-batch-service/src/main/java/org/flowable/batch/service/impl/BatchQueryImpl.java:68

    protected boolean withoutTenantId;

    public BatchQueryImpl() {
    }

    public BatchQueryImpl(CommandContext commandContext, BatchServiceConfiguration batchServiceConfiguration) {
        super(commandContext);
        this.batchServiceConfiguration = batchServiceConfiguration;
    }

    public BatchQueryImpl(CommandExecutor commandExecutor, BatchServiceConfiguration batchServiceConfiguration) {
        super(commandExecutor);
        this.batchServiceConfiguration = batchServiceConfiguration;
    }

    @Override
    public BatchQuery batchId(String batchId) {
        if (batchId == null) {
            throw new FlowableIllegalArgumentException("Provided batch id is null");
        }
        this.id = batchId;
        return this;
    }

    @Override
    public BatchQuery batchType(String batchType) {
        if (batchType == null) {
            throw new FlowableIllegalArgumentException("Provided batch type is null");
        }
        this.batchType = batchType;
        return this;
    }

    @Override
    public BatchQuery batchTypes(Collection<String> batchTypes) {
        if (batchTypes == null || batchTypes.isEmpty()) {
            throw new FlowableIllegalArgumentException("Provided batch types must be provided and not empty");

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the actual batch id string (e.g. from Batch.getId() or the event payload)
2. Check the id for null before building the query, and fail early with a clearer application-level error
3. If the id is genuinely absent, look up the batch by searchKey or batchType instead

Example fix

// before
Batch batch = batchService.createBatchQuery().batchId(msg.getBatchId()).singleResult();
// after
if (msg.getBatchId() == null) {
    throw new IllegalStateException("Message does not carry a batch id");
}
Batch batch = batchService.createBatchQuery().batchId(msg.getBatchId()).singleResult();

if (batchId == null || batchId.isEmpty()) {
    throw new IllegalArgumentException("batchId is required for BatchQuery.batchId()");
}
Batch batch = batchService.createBatchQuery().batchId(batchId).singleResult();

boolean hasBatchId(String id) { return id != null && !id.isEmpty(); }

try {
    batch = batchService.createBatchQuery().batchId(batchId).singleResult();
} catch (FlowableIllegalArgumentException e) {
    throw new IllegalArgumentException("Cannot look up batch: id missing in payload", e);
}

When it happens

Trigger: Calling batchService.createBatchQuery().batchId(null), or passing a batch id read from a message/DTO that was not populated.

Common situations: Handlers of batch completion events that only carry a batch reference; deserialization of a payload where the id field was absent.

Related errors

• status is null
• scopeId is null
• subScopeId is null
• scopeType is null
• tenantIdLike is null

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