flowable/flowable-engine · error · FlowableIllegalArgumentException

type is required when adding a new process instance identity

Error message

type is required when adding a new process instance identity link

What it means

FlowableIllegalArgumentException thrown by AddIdentityLinkForProcessInstanceCmd.validateParams when the identity link 'type' argument is null. Identity links (assignee, candidate, starter, custom types) require a type to record what kind of relation is being attached to the process instance. The command refuses to run without it.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java:59

    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 FlowableIllegalArgumentException("processInstanceId is null");
        }

        if (type == null) {
            throw new FlowableIllegalArgumentException("type is required when adding a new process instance identity link");
        }

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

    }

    @Override
    public Void execute(CommandContext commandContext) {

        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processInstance = executionEntityManager.findById(processInstanceId);

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a non-null identity link type, e.g. IdentityLinkType.ASSIGNEE, IdentityLinkType.CANDIDATE, or a custom string.
2. If the type comes from config/data, add a null check or default value before invoking the runtime service call.
3. Validate input at the API/DTO layer so the type is required before reaching the Flowable command.

Example fix

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

if (linkType == null || linkType.isEmpty()) {
    throw new IllegalArgumentException("identity link type is required");
}

boolean hasType(String t) { return t != null && !t.trim().isEmpty(); }

try {
    runtimeService.addUserIdentityLink(piId, userId, linkType);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("type is required")) {
        // fix: supply a valid IdentityLinkType
    }
    throw e;
}

When it happens

Trigger: Calling RuntimeService.addUserIdentityLink(processInstanceId, userId, type), addGroupIdentityLink, or addParticipantStart/addIdentityLinkForProcessInstance with a null 'type' argument while processInstanceId and userId/groupId are provided.

Common situations: Building the type string dynamically (e.g. from a variable or config lookup) and getting null; passing null for custom link types; mapping code that omits the type field from a DTO; upgrading code that previously called a convenience method that defaulted the type.

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

• userId and groupId cannot both be null
• userId and groupId cannot both be null
• Error retrieving app engine info
• No deployment id available
• No resource name available

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