flowable/flowable-engine · error · FlowableIllegalArgumentException

batchSize has to be larger than 0

Error message

batchSize has to be larger than 0

What it means

DeleteHistoricCaseInstancesUsingBatchesCmd deletes historic CMMN case instances in configurable batch sizes. Before executing it validates its inputs, and it requires batchSize strictly greater than 0. The library throws FlowableIllegalArgumentException because a non-positive batch size would make the batch deletion loop impossible or destructive (deleting everything at once).

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/delete/DeleteHistoricCaseInstancesUsingBatchesCmd.java:68

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

    public DeleteHistoricCaseInstancesUsingBatchesCmd(HistoricCaseInstanceQueryImpl query, int batchSize, String batchName, boolean sequential) {
        this.historicCaseInstanceQuery = query;
        this.batchSize = batchSize;
        this.batchName = batchName;
        this.sequential = sequential;
    }

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

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

        CmmnEngineConfiguration engineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        BatchService batchService = engineConfiguration.getBatchServiceConfiguration()
                .getBatchService();

        long numberOfCaseInstancesToDelete = historicCaseInstanceQuery.count();

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

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

        populateQueryNode(queryNode, historicCaseInstanceQuery);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set batchSize to a positive integer, e.g. 100 or 1000, before creating the command
2. Check any config/property feeding batchSize and give it a sensible default (>0)
3. Validate batchSize > 0 at your API boundary before invoking the delete command

Example fix

// before
cmmnEngineConfiguration.getCommandExecutor().execute(new DeleteHistoricCaseInstancesUsingBatchesCmd(query, 0));
// after
cmmnEngineConfiguration.getCommandExecutor().execute(new DeleteHistoricCaseInstancesUsingBatchesCmd(query, 100));

if (batchSize <= 0) throw new IllegalArgumentException("batchSize must be > 0, got: " + batchSize);

try { cmd.execute(...) } catch (FlowableIllegalArgumentException e) { log.error("Bad batch params: {}", e.getMessage()); }

When it happens

Trigger: Calling CmmnHistoryService.createHistoricCaseInstanceQuery()...historic data deletion via a command/batch helper with batchSize <= 0 (0 or negative), typically from a misconfigured cleanup job or a config value read from properties/env that defaulted to 0.

Common situations: A batch-size config key absent from configuration so it parses as 0; a user setting batchSize=-1 intending 'unlimited'; code that divides total count to compute batch size when count is 0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• There are no case instance ids to delete
• At most one non-null value can be provided for timeDate, tim
• An end date can only be provided when rescheduling a timer u
• comment is null
• model is null

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