flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceIds are null

Error message

processInstanceIds are null

What it means

DeleteProcessInstancesByIdCmd validates that the collection of process instance ids is non-null before iterating and throwing FlowableIllegalArgumentException. Null collections are rejected outright; an empty collection simply deletes nothing.

Source

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

/**
 * @author Christopher Welsch
 */
public class DeleteProcessInstancesByIdCmd implements Command<Void>, Serializable {

    private static final long serialVersionUID = 1L;
    protected Collection<String> processInstanceIds;
    protected String deleteReason;

    public DeleteProcessInstancesByIdCmd(Collection<String> processInstanceIds, String deleteReason) {
        this.processInstanceIds = processInstanceIds;
        this.deleteReason = deleteReason;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        if (processInstanceIds == null) {
            throw new FlowableIllegalArgumentException("processInstanceIds are null");
        }

        Set<String> processInstanceIdSet = new HashSet<>(processInstanceIds);
        for (String processInstanceId : processInstanceIdSet) {
            executeSingleDelete(commandContext, processInstanceId);
        }
        return null;
    }

    protected Void executeSingleDelete(CommandContext commandContext, String processInstanceId) {
        DeleteProcessInstanceCmd command = new DeleteProcessInstanceCmd(processInstanceId, deleteReason);
        return command.execute(commandContext);
    }
}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Initialize the ids collection, e.g. new ArrayList<>() instead of null.
2. Guard the call site: if (ids == null) ids = Collections.emptyList();
3. Validate the request payload before mapping into the service call.
4. Consider checking isEmpty() too, since an empty collection is a no-op that may indicate a bug upstream.

Example fix

// before
runtimeService.deleteProcessInstances(processInstanceIds, "bulk cancel");
// after
if (processInstanceIds == null) {
    processInstanceIds = Collections.emptyList();
}
runtimeService.deleteProcessInstances(processInstanceIds, "bulk cancel");

if (processInstanceIds == null) processInstanceIds = Collections.emptyList();

try { rs.deleteProcessInstances(ids, reason); } catch (FlowableIllegalArgumentException e) { log.warn("No ids provided", e); }

When it happens

Trigger: Calling runtimeService.deleteProcessInstances(ids, reason) with a null List/Set, typically from an unpopulated query result or a missing method argument.

Common situations: Bulk-cancel endpoints where the caller sent no ids and the server code forwards the raw (null) list; ids collected in a loop that never executed; deserialization of JSON with a missing ids field yielding null.

Related errors

• processInstanceIds is null
• processInstanceId is null
• taskId and taskIds are null
• event is null
• Error retrieving app engine info

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