flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot find process definition with id

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.

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

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

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

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

• Cannot find process definition with id
• Cannot find process definition with id
• Cannot find process definition with id
• Cannot find process definition with id
• No process definition found with id

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

Appendix: 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)