Activiti/Activiti · 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

Activiti throws ActivitiIllegalArgumentException when the identity link type is null in AddIdentityLinkForProcessInstanceCmd. The type (e.g. candidate, participant) is required to classify the link. validateParams enforces it right after the processInstanceId check.

Solutions

1. Pass a non-null type such as IdentityLinkType.CANDIDATE, IdentityLinkType.PARTICIPANT, or a custom value.
2. Define custom type constants instead of raw strings to avoid nulls.
3. Validate the type parameter in the caller.

Example fix

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

if (linkType == null) {
    throw new IllegalArgumentException("Identity link type is required");
}

boolean hasLinkType(String type) { return type != null && !type.trim().isEmpty(); }

try {
    runtimeService.addUserIdentityLink(pid, userId, groupId, type);
} catch (ActivitiIllegalArgumentException e) {
    log.error("Identity link type missing: {}", e.getMessage());
}

When it happens

Trigger: Calling addUserIdentityLink/addGroupIdentityLink on a process instance with type=null, e.g. a type variable loaded from config or task data that is unset.

Common situations: Custom identity-link types read from properties files that failed to load; typos where the constant referenced is actually null; reflection-based invocation passing null.

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

• processDefinitionId is null
• processInstanceId is null
• userId and groupId cannot both be null
• userId and groupId cannot both be null
• Candidate group list is null

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/9ae62b72bd9ff625. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java:70

        String groupId,
        String type,
        byte[] details
    ) {
        validateParams(processInstanceId, userId, groupId, type);
        this.processInstanceId = processInstanceId;
        this.userId = userId;
        this.groupId = groupId;
        this.type = type;
        this.details = details;
    }

    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");
        }
    }

    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionEntityManager = commandContext.getExecutionEntityManager();
        ExecutionEntity processInstance = executionEntityManager.findById(processInstanceId);

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

View on GitHub (pinned to 56435b1a97)