flowable/flowable-engine · error · FlowableIllegalArgumentException

processInstanceId is null

Error message

processInstanceId is null

What it means

DeleteProcessInstanceCmd requires a non-null processInstanceId; it validates this before any database lookup and throws FlowableIllegalArgumentException. It is a fast-fail guard so callers do not hit a downstream NPE in findById.

Source

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

/**
 * @author Joram Barrez
 */
public class DeleteProcessInstanceCmd implements Command<Void>, Serializable {

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

    public DeleteProcessInstanceCmd(String processInstanceId, String deleteReason) {
        this.processInstanceId = processInstanceId;
        this.deleteReason = deleteReason;
    }

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

        ExecutionEntity processInstanceEntity = CommandContextUtil.getExecutionEntityManager(commandContext).findById(processInstanceId);
        if (processInstanceEntity == null) {
            throw new FlowableObjectNotFoundException("No process instance found for id '" + processInstanceId + "'", ProcessInstance.class);
        }
        if (processInstanceEntity.isDeleted()) {
            return null;
        }

        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, processInstanceEntity.getProcessDefinitionId())) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            compatibilityHandler.deleteProcessInstance(processInstanceId, deleteReason);
        } else {
            CommandContextUtil.getExecutionEntityManager(commandContext).deleteProcessInstance(processInstanceEntity.getProcessInstanceId(), deleteReason, false, true);
        }

        return null;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the id variable is set before calling deleteProcessInstance.
2. Validate/fail early in your own code when the id is absent.
3. If ids come from user input, reject empty/null values at the API boundary.
4. Check you are passing the process instance id, not the execution id or business key.

Example fix

// before
runtimeService.deleteProcessInstance(processInstanceId, "cancelled");
// after
if (processInstanceId == null) {
    throw new IllegalArgumentException("processInstanceId required");
}
runtimeService.deleteProcessInstance(processInstanceId, "cancelled");

if (processInstanceId == null || processInstanceId.isBlank()) throw new IllegalArgumentException("processInstanceId required");

try { rs.deleteProcessInstance(id, reason); } catch (FlowableIllegalArgumentException e) { log.warn("Missing instance id", e); }

When it happens

Trigger: Calling runtimeService.deleteProcessInstance(null, reason), or passing a variable that was never assigned/resolved (e.g. from an unbound expression or method parameter).

Common situations: Dynamic code where the instance id comes from a request body or process variable that is missing; copy-paste code passing the wrong variable; bulk-delete helpers that forward null entries.

Related errors

• ProcessInstanceId cannot be null.
• processInstanceIds are null
• taskId and taskIds are null
• event is null
• The process instance id is mandatory, but '${processInstance

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