flowable/flowable-engine · error · FlowableIllegalArgumentException

caseInstanceId is null

Error message

caseInstanceId is null

What it means

AddIdentityLinkForCaseDefinitionCmd's case-instance counterpart validates that a non-null caseInstanceId is supplied when attaching an identity link to a case instance. A null id leaves no target scope, so validateParams throws FlowableIllegalArgumentException.

Source

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

    protected String userId;

    protected String groupId;

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Capture the id returned by cmmnRuntimeService.startCaseInstance(...) and pass it to identity-link calls
2. Null-check the instance id at the caller before invoking the API
3. Use caseInstance.getId() from a CaseInstance query result rather than a hand-copied value

Example fix

// before
runtimeService.addIdentityLink(caseInstanceId, userId, null, IdentityLinkType.PARTICIPANT);
// after
if (caseInstanceId == null) throw new IllegalArgumentException("caseInstanceId is required");
runtimeService.addIdentityLink(caseInstanceId, userId, null, IdentityLinkType.PARTICIPANT);

if (caseInstanceId == null) throw new IllegalArgumentException("caseInstanceId is required");
runtimeService.addIdentityLink(caseInstanceId, userId, groupId, type);

boolean hasInstanceId(String id) { return id != null && !id.isBlank(); }

try {
    runtimeService.addIdentityLink(caseInstanceId, userId, groupId, type);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("caseInstanceId missing: " + e.getMessage());
}

When it happens

Trigger: Calling cmmnRuntimeService.addIdentityLink(caseInstanceId, userId, groupId, type) with a null caseInstanceId — e.g. the instance variable was never set, or the case was started elsewhere and its id wasn't propagated.

Common situations: Workflow orchestration code losing the case instance id between steps, REST callers omitting the instance id, or confusing taskId with caseInstanceId variables.

Related errors

• taskId is null
• identityId is null
• caseDefinitionId is null
• Cannot find case instance with id
• Could not find reactivation listener plan item instance in c

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