flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot find process definition with id ${processDefinitionId

Error message

Cannot find process definition with id ${processDefinitionId}

What it means

After parameter validation, DeleteIdentityLinkForProcessDefinitionCmd looks up the process definition entity by id. If the entity manager returns null (id never existed, or the definition was deleted), Flowable throws FlowableObjectNotFoundException with ProcessDefinition.class as the reference type.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/DeleteIdentityLinkForProcessDefinitionCmd.java:65

    }

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

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

    @Override
    public Void execute(CommandContext commandContext) {
        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        ProcessDefinitionEntity processDefinition = processEngineConfiguration.getProcessDefinitionEntityManager().findById(processDefinitionId);

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

        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {
            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();
            compatibilityHandler.deleteCandidateStarter(processDefinitionId, userId, groupId);
            return null;
        }

        processEngineConfiguration.getIdentityLinkServiceConfiguration().getIdentityLinkService()
            .deleteProcessDefinitionIdentityLink(processDefinition.getId(), userId, groupId);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the id with repositoryService.createProcessDefinitionQuery().processDefinitionId(id).singleResult() before deleting the link.
2. If the id came from another environment, re-resolve it by key and version (processDefinitionQuery().processDefinitionKeyLatestVersion()).
3. Handle FlowableObjectNotFoundException gracefully if the definition may have been undeployed concurrently.

Example fix

// before
repositoryService.deleteCandidateStarterUser(processDefinitionId, userId);
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(processDefinitionId).singleResult();
if (pd != null) {
    repositoryService.deleteCandidateStarterUser(processDefinitionId, userId);
}

ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(pdId).singleResult();
if (pd == null) {
    throw new IllegalStateException("Unknown process definition: " + pdId);
}

boolean definitionExists(RepositoryService rs, String pdId) {
    return pdId != null && rs.createProcessDefinitionQuery().processDefinitionId(pdId).count() > 0;
}

try {
    repositoryService.deleteCandidateStarterUser(pdId, userId);
} catch (FlowableObjectNotFoundException e) {
    log.warn("Process definition {} no longer exists; skipping link deletion", pdId);
}

When it happens

Trigger: Calling deleteProcessDefinitionIdentityLink / deleteCandidateStarterUser with a processDefinitionId that does not match any deployed definition, or that belonged to a since-deleted deployment.

Common situations: Hard-coded ids from another environment (test vs prod); definition deleted via cascade deployment cleanup; tenant-specific lookups returning a different definition than expected.

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