What causes "Cannot find process definition with id ${processDefinitionId}" in flowable/flowable-engine?

flowable/flowable-engine · error · ActivitiObjectNotFoundException

Cannot find process definition with id ${processDefinitionId

Error message

Cannot find process definition with id ${processDefinitionId}

What it means

After passing validation, the command loads the process definition via the ProcessDefinitionEntityManager. If no definition exists with the given id (it was deleted, never deployed in this database, or the id is malformed), it throws ActivitiObjectNotFoundException referencing ProcessDefinition.class.

Source

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

    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.deleteIdentityLink(userId, groupId);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify existence first: repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult(); skip if null.
Confirm you are connected to the repository database where the definition was deployed.
Re-resolve the id from the definition key + version instead of caching ids across deployments.
Catch ActivitiObjectNotFoundException and treat the link removal as a no-op if the definition is gone.

Example fix

// before
repositoryService.deleteCandidateStarterGroup(processDefinitionId, "sales");
// after
if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(processDefinitionId).count() > 0) {
    repositoryService.deleteCandidateStarterGroup(processDefinitionId, "sales");
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(processDefinitionId).count() == 0) {
    return; // definition not present in this database
}

Try / catch

try {
    repositoryService.deleteProcessDefinitionIdentityLink(defId, userId, groupId);
} catch (ActivitiObjectNotFoundException e) {
    log.warn("Process definition {} not found; skipping identity link removal", defId);
}

Prevention

Never cache process definition ids across environments or redeployments
Re-resolve ids from key + latestVersion at cleanup time
Check deployment deletions earlier in the same pipeline before removing identity links

When it happens

Trigger: Calling deleteProcessDefinitionIdentityLink/deleteCandidateStarterUser/Group with a processDefinitionId that does not exist in ACT_RE_PROCDEF — wrong database, deleted deployment, stale id after redeployment, or id of a different entity type.

Common situations: Multi-environment setups where ids from test are replayed against production; cascade job that deleted the deployment earlier in the same transaction; ids serialized and reused after redeploying a new version.

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/ac3a7eadf7f0a891. Report an issue: GitHub.