flowable/flowable-engine · error · ActivitiIllegalArgumentException

processInstanceId is null

Error message

processInstanceId is null

What it means

DeleteProcessInstanceCmd requires a non-null processInstanceId. When it is null the command throws ActivitiIllegalArgumentException before delegating to ExecutionEntityManager.deleteProcessInstance, since there is no instance to terminate. Fail-fast validation of a mandatory parameter.

Solutions

1. Verify the processInstanceId came from startProcessInstanceX() or a runtimeService.createProcessInstanceQuery() hit
2. Null-check the id before calling deleteProcessInstance
3. Fix upstream logic that produced a null id (e.g. .singleResult() returning null)

Example fix

// before
runtimeService.deleteProcessInstance(processInstanceId, "cancelled");
// after
if (processInstanceId != null) {
    runtimeService.deleteProcessInstance(processInstanceId, "cancelled");
}

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

boolean validProcessInstanceId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    runtimeService.deleteProcessInstance(processInstanceId, deleteReason);
} catch (ActivitiIllegalArgumentException e) {
    log.error("Process instance deletion skipped: {}", e.getMessage());
}

When it happens

Trigger: Calling RuntimeService.deleteProcessInstance(null, reason), or new DeleteProcessInstanceCmd(null, reason) with an uninitialized id variable.

Common situations: Deleting from a flow where the process instance was never started (startProcessInstanceByX returned null); using a result of a query that found nothing; id taken from an unbound variable in a loop.

Related errors

• ProcessInstanceId cannot be null.
• Description is null
• executionId is null
• id is null
• key is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/DeleteProcessInstanceCmd.java:38

/**
 * @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 ActivitiIllegalArgumentException("processInstanceId is null");
        }

        commandContext
                .getExecutionEntityManager()
                .deleteProcessInstance(processInstanceId, deleteReason);
        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)