{"record":{"id":"d22caaaf0733f63b","repo":"flowable/flowable-engine","slug":"cannot-find-process-definition-with-id","errorCode":null,"errorMessage":"Cannot find process definition with id ","messagePattern":"Cannot find process definition with id ","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessDefinitionCmd.java","lineNumber":65,"sourceCode":"    }\n\n    protected void validateParams(String userId, String groupId, String processDefinitionId) {\n        if (processDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"processDefinitionId is null\");\n        }\n\n        if (userId == null && groupId == null) {\n            throw new FlowableIllegalArgumentException(\"userId and groupId cannot both be null\");\n        }\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        ProcessDefinitionEntity processDefinition = processEngineConfiguration.getProcessDefinitionEntityManager().findById(processDefinitionId);\n\n        if (processDefinition == null) {\n            throw new FlowableObjectNotFoundException(\"Cannot find process definition with id \" + processDefinitionId, ProcessDefinition.class);\n        }\n\n        if (Flowable5Util.isFlowable5ProcessDefinition(processDefinition, commandContext)) {\n            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();\n            compatibilityHandler.addCandidateStarter(processDefinitionId, userId, groupId);\n            return null;\n        }\n\n        IdentityLinkEntity identityLinkEntity = processEngineConfiguration.getIdentityLinkServiceConfiguration()\n                .getIdentityLinkService().createProcessDefinitionIdentityLink(processDefinition.getId(), userId, groupId);\n        processDefinition.getIdentityLinks().add(identityLinkEntity);\n\n        return null;\n    }\n\n}\n","sourceCodeStart":47,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessDefinitionCmd.java#L47-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fetch the current id via repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult() and use its getId().","Verify the definition exists in the same database/tenant the engine is connected to.","Catch FlowableObjectNotFoundException and surface a clear message if the id may be stale."],"exampleFix":"// before\nrepositoryService.addCandidateStarterProcessDefinition(\"myProcess:1:4\", \"kermit\", null); // stale/unknown id\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n        .processDefinitionKey(\"myProcess\").latestVersion().singleResult();\nrepositoryService.addCandidateStarterProcessDefinition(pd.getId(), \"kermit\", null);","handlingStrategy":"try-catch","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n        .processDefinitionId(defId).singleResult();\nif (pd == null) {\n    throw new IllegalStateException(\"Unknown process definition id: \" + defId);\n}","typeGuard":"boolean definitionExists(String defId) {\n    return defId != null && repositoryService.createProcessDefinitionQuery()\n        .processDefinitionId(defId).count() > 0;\n}","tryCatchPattern":"try {\n    repositoryService.addCandidateStarterProcessDefinition(defId, userId, groupId);\n} catch (FlowableObjectNotFoundException e) {\n    log.error(\"Process definition {} not found; re-resolve latest version\", defId);\n}","preventionTips":["Always look up ids via query APIs instead of storing them across deployments.","Use latestVersion + definition key to survive redeployments.","Account for tenant filtering when definitions are tenant-scoped."],"tags":["not-found","process-definition","lookup"],"backgroundTag":"entity-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}