flowable/flowable-engine · error · FlowableIllegalArgumentException

type is required when adding a new case instance identity li

Error message

type is required when adding a new case instance identity link

What it means

AddIdentityLinkForCaseInstanceCmd.validateParams throws FlowableIllegalArgumentException when the identity link 'type' (e.g. 'participant', 'owner', custom type) is null. Flowable requires every identity link to carry a type so it can be categorized when persisted to the identity link tables. The command refuses to run rather than persisting an uncategorized link.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/AddIdentityLinkForCaseInstanceCmd.java:57

    protected String type;

    public AddIdentityLinkForCaseInstanceCmd(String caseInstanceId, String userId, String groupId, String type) {
        validateParams(caseInstanceId, userId, groupId, type);
        this.caseInstanceId = caseInstanceId;
        this.userId = userId;
        this.groupId = groupId;
        this.type = type;
    }

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

        if (caseInstanceId == null) {
            throw new FlowableIllegalArgumentException("caseInstanceId is null");
        }

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

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

    }

    @Override
    public Void execute(CommandContext commandContext) {
        CmmnEngineConfiguration cmmnEngineConfiguration = CommandContextUtil.getCmmnEngineConfiguration(commandContext);
        CaseInstanceEntityManager caseInstanceEntityManager = cmmnEngineConfiguration.getCaseInstanceEntityManager();
        CaseInstanceEntity caseInstance = caseInstanceEntityManager.findById(caseInstanceId);

        if (caseInstance == null) {
            throw new FlowableObjectNotFoundException("Cannot find case instance with id " + caseInstanceId, CaseInstanceEntity.class);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a valid identity link type (e.g. IdentityLinkType.PARTICIPANT or a custom string) when calling addIdentityLink APIs
2. Validate the type parameter is non-null in your own code before invoking the runtime service
3. If the type comes from a REST payload or config, add defaulting logic (e.g. default to "participant")

Example fix

// before
cmmnRuntimeService.addIdentityLinkForCaseInstance(caseInstanceId, userId, null);
// after
cmmnRuntimeService.addIdentityLinkForCaseInstance(caseInstanceId, userId, IdentityLinkType.PARTICIPANT);

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

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

try {
    cmmnRuntimeService.addIdentityLinkForCaseInstance(caseId, userId, type);
} catch (FlowableIllegalArgumentException e) {
    log.error("Invalid identity link arguments: {}", e.getMessage());
}

When it happens

Trigger: Calling CmmnRuntimeService.addUserIdentityLinkForCaseInstance(caseInstanceId, userId) style APIs or constructing AddIdentityLinkForCaseInstanceCmd directly with a null type parameter — e.g. passing a null link type variable from configuration or a REST request body missing the 'type' field.

Common situations: REST clients omitting the type field in the request body; custom code building identity links where the type comes from an unset enum/config value; migration scripts copying links from process instances without mapping 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
• Either set the user id or the group id for an identity link,
• taskId is null
• type is required when adding a new task identity link
• identityId is null

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