flowable/flowable-engine · error · ActivitiIllegalArgumentException

type is required when adding a new process instance…

Error message

type is required when adding a new process instance identity link

What it means

AddIdentityLinkForProcessInstanceCmd requires a non-null link type when adding a process instance identity link. validateParams throws ActivitiIllegalArgumentException because without a type the link has no semantics and cannot be stored.

Solutions

1. Pass an explicit type such as IdentityLinkType.PARTICIPANT or a custom 'starter' style type
2. Default the type when null: type == null ? IdentityLinkType.PARTICIPANT : type
3. Validate request payloads for the type field at the API boundary

Example fix

// before
runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, linkType); // null
// after
String t = linkType != null ? linkType : IdentityLinkType.PARTICIPANT;
runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, t);

if (linkType == null) {
    linkType = IdentityLinkType.PARTICIPANT; // or reject
}

try {
    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("type is required")) {
        runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, IdentityLinkType.PARTICIPANT);
    } else { throw e; }
}

When it happens

Trigger: Calling runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null) or the group variant with a null type; constructing the command with type == null.

Common situations: Link type read from configuration/JSON where the field is absent; variable shadowing or swapped arguments; assuming a default type is applied automatically (none is).

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
• processInstanceId is null
• 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/c2a69aba0daa2f52. Report an issue: GitHub.

Appendix: source

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

    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) {
            throw new ActivitiObjectNotFoundException("Cannot find process instance with id " + processInstanceId, ExecutionEntity.class);
        }

        processInstance.addIdentityLink(userId, groupId, type);

View on GitHub (pinned to d6d39ce1c6)