flowable/flowable-engine · error · ActivitiIllegalArgumentException

processDefinitionId is null

Error message

processDefinitionId is null

What it means

AddIdentityLinkForProcessDefinitionCmd attaches an identity link to a process definition. validateParams requires a non-null processDefinitionId, since the command has no target to attach the link to otherwise. Flowable throws ActivitiIllegalArgumentException immediately.

Solutions

1. Pass the actual process definition id (obtained from repositoryService.createProcessDefinitionQuery())
2. Verify the variable holding the id is populated before the call
3. If you only have the key, look up the latest definition id first and pass that

Example fix

// before
repositoryService.addUserIdentityLinkForProcessDefinition(defId, userId); // defId null
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult();
repositoryService.addUserIdentityLinkForProcessDefinition(def.getId(), userId);

if (processDefinitionId == null || processDefinitionId.isEmpty()) {
    throw new IllegalArgumentException("processDefinitionId is required");
}

try {
    repositoryService.addUserIdentityLinkForProcessDefinition(defId, userId);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("processDefinitionId")) {
        // resolve the id from a query and retry
    } else { throw e; }
}

When it happens

Trigger: Calling repositoryService.addUserIdentityLinkForProcessDefinition(null, userId) or the groupId variant with a null processDefinitionId; constructing the command directly with a null id.

Common situations: The process definition id was meant to be resolved from a deployment result or process variable that was not set; confusing processDefinitionId with processDefinitionKey.

Related errors

• processDefinitionId is null
• userId and groupId cannot both be 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/4c9752a8b6612e1f. Report an issue: GitHub.

Appendix: source

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

    private static final long serialVersionUID = 1L;

    protected String processDefinitionId;

    protected String userId;

    protected String groupId;

    public AddIdentityLinkForProcessDefinitionCmd(String processDefinitionId, String userId, String groupId) {
        validateParams(userId, groupId, processDefinitionId);
        this.processDefinitionId = processDefinitionId;
        this.userId = userId;
        this.groupId = groupId;
    }

    protected void validateParams(String userId, String groupId, String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("processDefinitionId is null");
        }

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

    @Override
    public Void execute(CommandContext commandContext) {
        ProcessDefinitionEntity processDefinition = commandContext
                .getProcessDefinitionEntityManager()
                .findProcessDefinitionById(processDefinitionId);

        if (processDefinition == null) {
            throw new ActivitiObjectNotFoundException("Cannot find process definition with id " + processDefinitionId, ProcessDefinition.class);
        }

        processDefinition.addIdentityLink(userId, groupId);

View on GitHub (pinned to d6d39ce1c6)