flowable/flowable-engine · error · FlowableObjectNotFoundException

Cannot find process definition with id

Error message

Cannot find process definition with id 

What it means

AddIdentityLinkForProcessDefinitionCmd.execute() looks up the process definition via the ProcessDefinitionEntityManager and throws FlowableObjectNotFoundException when no definition matches the given id. Unlike the null checks, the id was provided but does not correspond to any deployed definition.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessDefinitionCmd.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.addCandidateStarter(processDefinitionId, userId, groupId);
            return null;
        }

        IdentityLinkEntity identityLinkEntity = processEngineConfiguration.getIdentityLinkServiceConfiguration()
                .getIdentityLinkService().createProcessDefinitionIdentityLink(processDefinition.getId(), userId, groupId);
        processDefinition.getIdentityLinks().add(identityLinkEntity);

        return null;
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Fetch the current id via repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() and use its getId().
2. Verify the definition exists in the same database/tenant the engine is connected to.
3. Catch FlowableObjectNotFoundException and surface a clear message if the id may be stale.

Example fix

// before
repositoryService.addCandidateStarterProcessDefinition("myProcess:1:4", "kermit", null); // stale/unknown id
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey("myProcess").latestVersion().singleResult();
repositoryService.addCandidateStarterProcessDefinition(pd.getId(), "kermit", null);

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

boolean definitionExists(String defId) {
    return defId != null && repositoryService.createProcessDefinitionQuery()
        .processDefinitionId(defId).count() > 0;
}

try {
    repositoryService.addCandidateStarterProcessDefinition(defId, userId, groupId);
} catch (FlowableObjectNotFoundException e) {
    log.error("Process definition {} not found; re-resolve latest version", defId);
}

When it happens

Trigger: Calling addCandidateStarterProcessDefinition with an id that was deleted, belongs to another engine's database, was mistyped, or a definition key passed where an id is expected.

Common situations: Stale ids after re-deployment or database cleanup; hardcoded ids from another environment; confusing definition key with definition id; tenant mismatch filtering the definition out.

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

• No process definition found with id ${processDefinitionId}
• Cannot find process definition with id ${processDefinitionId
• No process definition found for name:
• Process definition ${processDefinitionKey} was not found in
• No process definition found for key '{processDefinitionKey}'

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