flowable/flowable-engine · error · FlowableIllegalArgumentException

batchSize has to be larger than 0

Error message

batchSize has to be larger than 0

What it means

DeleteHistoricProcessInstancesUsingBatchesCmd.execute checks batchSize immediately after the null-query check; if batchSize <= 0 it throws FlowableIllegalArgumentException('batchSize has to be larger than 0'). The batch is split into chunks of batchSize instances, so a non-positive size cannot define valid batch parts.

Solutions

1. Call setBatchSize with a positive integer (e.g. 100) before executing the command.
2. Clamp or validate the batchSize value at the call site: Math.max(1, configuredSize).
3. Check the configuration property feeding batchSize is present and positive.

Example fix

// before
cmd.setBatchSize(0);
// after
if (batchSize <= 0) {
    batchSize = 100; // or throw a clear config error
}
cmd.setBatchSize(batchSize);

if (batchSize <= 0) {
    throw new IllegalArgumentException("batchSize must be > 0, got " + batchSize);
}
cmd.setBatchSize(batchSize);

try {
    managementService.executeCommand(cmd);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("batchSize has to be larger than 0")) {
        cmd.setBatchSize(DEFAULT_BATCH_SIZE);
        // retry
    } else {
        throw e;
    }
}

When it happens

Trigger: Constructing DeleteHistoricProcessInstancesUsingBatchesCmd and leaving batchSize at its default/0, or explicitly passing a zero or negative value (DeleteHistoricProcessInstancesUsingBatchesCmd.java:67).

Common situations: Default-initialized field never set by the caller; off-by-one or negative computed size (e.g. division of a small total); configuration property resolving to 0.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• query is null
• A channel key detection value is required for the channel…
• A group or a user is required to create an identity link.
• A group or a user is required to create an identity link.
• A request body was expected when executing the form submit.

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/delete/DeleteHistoricProcessInstancesUsingBatchesCmd.java:67

    protected int batchSize;
    protected boolean sequential;
    protected String batchName;

    public DeleteHistoricProcessInstancesUsingBatchesCmd(HistoricProcessInstanceQueryImpl query, int batchSize, String batchName, boolean sequential) {
        this.historicProcessInstanceQuery = query;
        this.batchSize = batchSize;
        this.batchName = batchName;
        this.sequential = sequential;
    }

    @Override
    public String execute(CommandContext commandContext) {
        if (historicProcessInstanceQuery == null) {
            throw new FlowableIllegalArgumentException("query is null");
        }

        if (batchSize <= 0) {
            throw new FlowableIllegalArgumentException("batchSize has to be larger than 0");
        }

        ProcessEngineConfigurationImpl engineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        BatchService batchService = engineConfiguration.getBatchServiceConfiguration()
                .getBatchService();

        long numberOfProcessInstancesToDelete = historicProcessInstanceQuery.count();

        ObjectNode batchConfiguration = engineConfiguration.getObjectMapper().createObjectNode();
        batchConfiguration.put("numberOfInstances", numberOfProcessInstancesToDelete);
        batchConfiguration.put("batchSize", batchSize);
        if (sequential) {
            batchConfiguration.put("sequential", true);
        }

        ObjectNode queryNode = batchConfiguration.putObject("query");

        populateQueryNode(queryNode, historicProcessInstanceQuery);

View on GitHub (pinned to d6d39ce1c6)