flowable/flowable-engine · error · FlowableIllegalArgumentException

query is null

Error message

query is null

What it means

DeleteHistoricProcessInstancesUsingBatchesCmd.execute validates its inputs before creating the batch. If the historicProcessInstanceQuery field is null it throws FlowableIllegalArgumentException('query is null'). The command cannot select which historic process instances to delete without a query, so null is rejected up front.

Source

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

 */
public class DeleteHistoricProcessInstancesUsingBatchesCmd implements Command<String> {

    protected HistoricProcessInstanceQueryImpl historicProcessInstanceQuery;
    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);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set a non-null HistoricProcessInstanceQuery on the command before executing it (setHistoricProcessInstanceQuery).
2. Create the query via historyService.createHistoricProcessInstanceQuery() and configure its filter.
3. Validate command fields before submitting it to the command executor.

Example fix

// before
DeleteHistoricProcessInstancesUsingBatchesCmd cmd = new DeleteHistoricProcessInstancesUsingBatchesCmd();
cmd.setBatchSize(10);
// after
DeleteHistoricProcessInstancesUsingBatchesCmd cmd = new DeleteHistoricProcessInstancesUsingBatchesCmd();
cmd.setHistoricProcessInstanceQuery(historyService.createHistoricProcessInstanceQuery().finished());
cmd.setBatchSize(10);

Objects.requireNonNull(query, "historicProcessInstanceQuery must be set");
cmd.setHistoricProcessInstanceQuery(query);
cmd.execute(commandContext);

try {
    managementService.executeCommand(new DeleteHistoricProcessInstancesUsingBatchesCmd(query, batchSize, sequential));
} catch (FlowableIllegalArgumentException e) {
    if ("query is null".equals(e.getMessage())) {
        // fix command construction and retry once
    } else {
        throw e;
    }
}

When it happens

Trigger: Executing DeleteHistoricProcessInstancesUsingBatchesCmd constructed without calling setHistoricProcessInstanceQuery (or with an explicit null HistoricProcessInstanceQuery) — DeleteHistoricProcessInstancesUsingBatchesCmd.java:63.

Common situations: Programmatic use of the command (e.g. via managementService command executor) forgetting to set the query; builder-style wiring where the query assignment is skipped on a code path; refactoring that removed the query initialization.

Related errors

• Error retrieving app engine info
• No deployment id available
• No resource name available
• appsDefinitionIds is null
• category is null

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