flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot find process definition with id

Error message

Cannot find process definition with id 

What it means

GetIdentityLinksForProcessDefinitionCmd.execute looks up the process definition via ProcessDefinitionEntityManager.findById and throws FlowableObjectNotFoundException when no definition matches processDefinitionId. Identity links for a definition (potential starters) hang off that entity, so a missing definition makes the operation impossible. This guards callers from an NPE on processDefinition.getIdentityLinks().

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetIdentityLinksForProcessDefinitionCmd.java:44

/**
 * @author Tijs Rademakers
 */
public class GetIdentityLinksForProcessDefinitionCmd implements Command<List<IdentityLink>>, Serializable {

    private static final long serialVersionUID = 1L;
    protected String processDefinitionId;

    public GetIdentityLinksForProcessDefinitionCmd(String processDefinitionId) {
        this.processDefinitionId = processDefinitionId;
    }

    @SuppressWarnings({ "unchecked", "rawtypes" })
    @Override
    public List<IdentityLink> execute(CommandContext commandContext) {
        ProcessDefinitionEntity processDefinition = CommandContextUtil.getProcessDefinitionEntityManager(commandContext).findById(processDefinitionId);

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

        List<IdentityLink> identityLinks = (List) processDefinition.getIdentityLinks();
        return identityLinks;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Confirm the id via repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult()
2. Resolve the id by key instead: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult()
3. Check tenant: add .processDefinitionTenantId(...) to your query to search the right tenant
4. Verify the deployment containing the definition still exists (deployment was not cascade-deleted)
5. Catch FlowableObjectNotFoundException and return an empty list or a clear user-facing message

Example fix

// before
List<IdentityLink> links = repositoryService.getIdentityLinksForProcessDefinition(defId);
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionId(defId).singleResult();
List<IdentityLink> links = (def != null)
    ? repositoryService.getIdentityLinksForProcessDefinition(defId)
    : Collections.emptyList();

ProcessDefinition def = repositoryService.createProcessDefinitionQuery().processDefinitionId(defId).singleResult();
if (def == null) throw new IllegalArgumentException("Unknown process definition: " + defId);

try {
  List<IdentityLink> links = repositoryService.getIdentityLinksForProcessDefinition(defId);
} catch (FlowableObjectNotFoundException e) {
  links = Collections.emptyList();
}

When it happens

Trigger: Calling RepositoryService.getIdentityLinksForProcessDefinition(definitionId) with an id that is not in ACT_RE_PROCDEF — typo, id from another deployment/database, or the definition was deleted via cascade delete of a deployment.

Common situations: Hardcoding a definition id that changed after redeployment; passing a model id instead of a process definition id; multi-tenant setup where the definition exists only in another tenant; environment drift between dev and prod databases.

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 ${processDefinitionId
• No process definition found for name:
• Process definition ${processDefinitionKey} was not found in
• The process instance with id '{processInstanceId}' could not
• No process definition found for key '{processDefinitionKey}'

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