What causes "query is null" in flowable/flowable-engine?

Null-check the query before passing it to deleteHistoricCaseInstances

flowable/flowable-engine · error · FlowableIllegalArgumentException

query is null

Error message

query is null

What it means

DeleteHistoricCaseInstancesCmd performs a bulk delete driven by a HistoricCaseInstanceQuery. If the query object itself is null, it throws FlowableIllegalArgumentException("query is null") before touching the database. This validates the query handle, not its results.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/DeleteHistoricCaseInstancesCmd.java:41

import org.flowable.common.engine.impl.interceptor.CommandContext;

/**
 * @author Tijs Rademakers
 */
public class DeleteHistoricCaseInstancesCmd implements Command<Object>, Serializable {

    private static final long serialVersionUID = 1L;
    
    protected HistoricCaseInstanceQueryImpl historicCaseInstanceQuery;

    public DeleteHistoricCaseInstancesCmd(HistoricCaseInstanceQueryImpl historicCaseInstanceQuery) {
        this.historicCaseInstanceQuery = historicCaseInstanceQuery;
    }

    @Override
    public Object execute(CommandContext commandContext) {
        if (historicCaseInstanceQuery == null) {
            throw new FlowableIllegalArgumentException("query is null");
        }
        
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        cmmnEngineConfiguration.getHistoricCaseInstanceEntityManager().deleteHistoricCaseInstances(historicCaseInstanceQuery);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Null-check the query before passing it to deleteHistoricCaseInstances
Always construct the query inline: historyService.createHistoricCaseInstanceQuery()...
Fix any helper that can return a null query

Example fix

// before
historyService.deleteHistoricCaseInstances(query);
// after
HistoricCaseInstanceQuery query = historyService.createHistoricCaseInstanceQuery().finished();
historyService.deleteHistoricCaseInstances(query);

Defensive patterns

Strategy: validation

Validate before calling

if (query == null) { query = historyService.createHistoricCaseInstanceQuery().finished(); }
historyService.deleteHistoricCaseInstances(query);

Type guard

HistoricCaseInstanceQuery orDefault(HistoricCaseInstanceQuery q, CmmnHistoryService hs) { return q != null ? q : hs.createHistoricCaseInstanceQuery(); }

Try / catch

try { historyService.deleteHistoricCaseInstances(query); }
catch (FlowableIllegalArgumentException e) { if ("query is null".equals(e.getMessage())) { throw new IllegalStateException("query must be built before bulk delete", e); } throw e; }

Prevention

Build queries inline rather than through nullable factory methods
Ensure helpers never return null queries
Wrap query construction and delete in one method to avoid uninitialized handles

When it happens

Trigger: Calling CmmnHistoryService.deleteHistoricCaseInstances(null) or passing a query variable that was never initialized (failed builder chain, null return from a factory method).

Common situations: A helper method returning null instead of a query on error; conditional construction where the else-branch forgets to build the query; reflection/config-driven query creation failing silently.

Related errors

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