flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceId is null

Error message

processInstanceId is null

What it means

DeleteHistoricProcessInstanceCmd.validate that the processInstanceId given to the command is not null before doing anything. The Flowable engine throws FlowableIllegalArgumentException when a caller invokes deletion of a historic process instance without supplying an id. This is an argument contract check, not a data lookup problem.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeleteHistoricProcessInstanceCmd.java:44

import org.flowable.engine.impl.util.CommandContextUtil;
import org.flowable.engine.impl.util.Flowable5Util;

/**
 * @author Frederik Heremans
 */
public class DeleteHistoricProcessInstanceCmd implements Command<Object>, Serializable {

    private static final long serialVersionUID = 1L;
    protected String processInstanceId;

    public DeleteHistoricProcessInstanceCmd(String processInstanceId) {
        this.processInstanceId = processInstanceId;
    }

    @Override
    public Object execute(CommandContext commandContext) {
        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("processInstanceId is null");
        }
        // Check if process instance is still running
        HistoricProcessInstanceEntity instance = CommandContextUtil.getHistoricProcessInstanceEntityManager(commandContext).findById(processInstanceId);

        if (instance == null) {
            throw new FlowableObjectNotFoundException("No historic process instance found with id: " + processInstanceId, HistoricProcessInstance.class);
        }
        if (instance.isDeleted()) {
            return null;
        }
        if (instance.getEndTime() == null) {
            throw new FlowableException("Process instance is still running, cannot delete " + instance);
        }

        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, instance.getProcessDefinitionId())) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            compatibilityHandler.deleteHistoricProcessInstance(processInstanceId);
            return null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null, valid historic process instance id to deleteHistoricProcessInstance
2. Verify the variable holding the id is populated before invoking the delete command
3. Fetch the id from the HistoricProcessInstanceQuery result instead of a stale reference

Example fix

// before
historyService.deleteHistoricProcessInstance(processInstanceId); // processInstanceId was null
// after
if (processInstanceId != null) {
    historyService.deleteHistoricProcessInstance(processInstanceId);
}

if (processInstanceId == null || processInstanceId.trim().isEmpty()) {
    throw new IllegalArgumentException("processInstanceId must be provided before deletion");
}

boolean hasProcessInstanceId = id -> id != null && !id.trim().isEmpty();

try {
    historyService.deleteHistoricProcessInstance(id);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("Null id passed to deleteHistoricProcessInstance", e);
}

When it happens

Trigger: Calling runtimeDataService/historyService APIs that end up executing DeleteHistoricProcessInstanceCmd with a null id, e.g. historyService.deleteHistoricProcessInstance(null), or passing a variable that was never assigned the process instance id.

Common situations: Developers storing the process instance id in a variable that failed to initialize, wiring the wrong variable into a delete call, or calling delete after a start call returned an object they did not keep the id from.

Related errors

• Must specify a historic case instance id to migrate
• Set of process instance ids is null
• Set of called process instance ids is null
• ProcessInstanceId cannot be null.
• processInstanceIds is null

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