flowable/flowable-engine · error · ActivitiIllegalArgumentException

processInstanceId is null

Error message

processInstanceId is null

What it means

Activiti/Flowable 5 throws this ActivitiIllegalArgumentException from DeleteIdentityLinkForProcessInstanceCmd when deleting a process-instance identity link without a processInstanceId. The command validates required parameters before touching the engine, refusing to proceed with a null execution id because the target process instance could never be located.

Solutions

1. Resolve a non-null processInstanceId before calling (e.g. taskService.createTaskQuery().taskId(taskId).singleResult().getProcessInstanceId()).
2. If working from a task with no process instance, use task identity-link APIs instead: taskService.deleteUserIdentityLink / deleteGroupIdentityLink.
3. Validate inputs early: skip or throw when processInstanceId is null before invoking the engine.
4. Use executionEntity.getId() from a live ExecutionEntity rather than a possibly-null cached value.

Example fix

// before
runtimeService.deleteProcessInstanceIdentityLink(procInstId, userId, null, "candidate");
// after
if (procInstId == null) {
    procInstId = taskService.createTaskQuery().taskId(taskId).singleResult().getProcessInstanceId();
}
runtimeService.deleteProcessInstanceIdentityLink(procInstId, userId, null, "candidate");

if (processInstanceId == null || processInstanceId.trim().isEmpty()) {
    throw new IllegalArgumentException("processInstanceId must be resolved before deleting an identity link");
}

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

try {
    runtimeService.deleteProcessInstanceIdentityLink(pid, userId, groupId, type);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("processInstanceId is null")) {
        throw new IllegalStateException("Caller bug: missing processInstanceId", e);
    }
    throw e;
}

When it happens

Trigger: Calling RuntimeService.deleteProcessInstanceIdentityLink(processInstanceId, userId, groupId, type) (or the equivalent IdentityLinkService command path) with processInstanceId == null.

Common situations: A variable holding the process instance id was never populated (e.g. an execution variable read back as null, or a standalone task with no process scope); also confusing taskId with processInstanceId in API calls.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• processInstanceId is null
• type is required when adding a new process instance…
• userId and groupId cannot both be null
• appDefinitionId is null
• identityId is null

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

Appendix: source

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

    protected String processInstanceId;

    protected String userId;

    protected String groupId;

    protected String type;

    public DeleteIdentityLinkForProcessInstanceCmd(String processInstanceId, String userId, String groupId, String type) {
        validateParams(userId, groupId, processInstanceId, type);
        this.processInstanceId = processInstanceId;
        this.userId = userId;
        this.groupId = groupId;
        this.type = type;
    }

    protected void validateParams(String userId, String groupId, String processInstanceId, String type) {
        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("processInstanceId is null");
        }

        if (type == null) {
            throw new ActivitiIllegalArgumentException("type is required when deleting a process identity link");
        }

        if (userId == null && groupId == null) {
            throw new ActivitiIllegalArgumentException("userId and groupId cannot both be null");
        }
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntity processInstance = commandContext.getExecutionEntityManager().findExecutionById(processInstanceId);

        if (processInstance == null) {
            throw new ActivitiObjectNotFoundException("Cannot find process instance with id " + processInstanceId, ExecutionEntity.class);
        }

View on GitHub (pinned to d6d39ce1c6)