flowable/flowable-engine · error · ActivitiIllegalArgumentException

processInstanceId is null

Error message

processInstanceId is null

What it means

AddIdentityLinkForProcessInstanceCmd attaches an identity link to a running process instance. validateParams requires a non-null processInstanceId because the link must target an existing execution. Flowable throws ActivitiIllegalArgumentException when it is null.

Solutions

1. Pass a valid process instance id from runtimeService.startProcessInstance...(...) or a ProcessInstance.getId()
2. Null-check the id variable before the call
3. Ensure the REST/form layer actually supplies the instance id

Example fix

// before
runtimeService.addUserIdentityLinkForProcessInstance(instanceId, userId, type); // null
// after
ProcessInstance pi = runtimeService.startProcessInstanceByKey("myProcess");
runtimeService.addUserIdentityLinkForProcessInstance(pi.getId(), userId, type);

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

try {
    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("processInstanceId")) {
        // obtain a valid instance id before retrying
    } else { throw e; }
}

When it happens

Trigger: Calling runtimeService.addUserIdentityLinkForProcessInstance(null, userId) or addGroupIdentityLinkForProcessInstance with null processInstanceId; constructing the command directly with null.

Common situations: The process instance was started asynchronously and the id variable was not yet assigned; a form/REST payload omitted the instance id; confusing processInstanceId with taskId.

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/a03cc5d386a73dcc. Report an issue: GitHub.

Appendix: source

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

    protected String userId;

    protected String groupId;

    protected String type;

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

    protected void validateParams(String processInstanceId, String userId, String groupId, String type) {

        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("processInstanceId is null");
        }

        if (type == null) {
            throw new ActivitiIllegalArgumentException("type is required when adding a new process instance 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) {

View on GitHub (pinned to d6d39ce1c6)