flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot find process definition with id ${processDefinitionId

Error message

Cannot find process definition with id ${processDefinitionId}

What it means

During execute, AddIdentityLinkForProcessDefinitionCmd looks up the process definition via ProcessDefinitionEntityManager.findProcessDefinitionById. If no definition exists for the given id, Flowable throws ActivitiObjectNotFoundException so the caller knows the target entity does not exist rather than silently doing nothing.

Source

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

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

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the id with repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult() before linking
  2. If you only have the key, resolve the latest definition id first
  3. Confirm you are connected to the database/environment where the definition was deployed

Example fix

// before
repositoryService.addUserIdentityLinkForProcessDefinition("myProcess", userId); // key, not id
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult();
repositoryService.addUserIdentityLinkForProcessDefinition(def.getId(), userId);
Defensive patterns

Strategy: validation

Validate before calling

ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionId(defId).singleResult();
if (def == null) {
    throw new IllegalStateException("No process definition for id " + defId);
}

Try / catch

try {
    repositoryService.addUserIdentityLinkForProcessDefinition(defId, userId);
} catch (ActivitiObjectNotFoundException e) {
    if (ProcessDefinition.class.equals(e.getObjectClass())) {
        // resolve latest definition by key and retry
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling addUserIdentityLinkForProcessDefinition with an id that was never deployed, already deleted, or that is actually a definition key instead of an id.

Common situations: Copying a definition id from another environment (test vs prod database); stale cached id after redeployment; passing the process definition key (e.g. 'myProcess') instead of the id (e.g. 'myProcess:1:4').

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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