{"record":{"id":"7095ea980bbd6d99","repo":"flowable/flowable-engine","slug":"cannot-find-process-instance-with-id","errorCode":null,"errorMessage":"Cannot find process instance with id ","messagePattern":"Cannot find process instance with id ","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java","lineNumber":75,"sourceCode":"\n        if (type == null) {\n            throw new FlowableIllegalArgumentException(\"type is required when adding a new process instance identity link\");\n        }\n\n        if (userId == null && groupId == null) {\n            throw new FlowableIllegalArgumentException(\"userId and groupId cannot both be null\");\n        }\n\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n\n        ExecutionEntityManager executionEntityManager = CommandContextUtil.getExecutionEntityManager(commandContext);\n        ExecutionEntity processInstance = executionEntityManager.findById(processInstanceId);\n\n        if (processInstance == null) {\n            throw new FlowableObjectNotFoundException(\"Cannot find process instance with id \" + processInstanceId, ExecutionEntity.class);\n        }\n\n        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, processInstance.getProcessDefinitionId())) {\n            Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();\n            compatibilityHandler.addIdentityLinkForProcessInstance(processInstanceId, userId, groupId, type);\n            return null;\n        }\n\n        IdentityLinkUtil.createProcessInstanceIdentityLink(processInstance, userId, groupId, type);\n        CommandContextUtil.getHistoryManager(commandContext).createProcessInstanceIdentityLinkComment(processInstance, userId, groupId, type, true);\n\n        return null;\n\n    }\n\n}\n","sourceCodeStart":57,"sourceCodeEnd":92,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java#L57-L92","documentation":"FlowableObjectNotFoundException thrown in AddIdentityLinkForProcessInstanceCmd.execute when no ExecutionEntity (process instance) exists for the given processInstanceId. Flowable looks the execution up via the ExecutionEntityManager and throws with the entity class ExecutionEntity attached so callers can discriminate the missing object type.","triggerScenarios":"Calling addUserIdentityLink / addGroupIdentityLink / addIdentityLinkForProcessInstance with a processInstanceId that does not exist, or that refers to an already-ended (historic) process instance whose runtime execution row was deleted.","commonSituations":"Storing a process instance id and using it after the instance completed or was aborted; id taken from the wrong field (e.g. a task id or historic id); wrong database/tenant environment where the instance was never created; typos or stale ids from a cache.","solutions":["Verify the processInstanceId is a current runtime instance via runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() before adding the link.","If the instance may have ended, fall back to the historic API (taskService/historyService) or add identity links on the historic entity instead.","Fix id plumbing: make sure the id comes from ProcessInstance.getId() of the correct deployment/database."],"exampleFix":"// before\nruntimeService.addUserIdentityLink(processInstanceId, userId, IdentityLinkType.PARTICIPANT);\n// after\nProcessInstance pi = runtimeService.createProcessInstanceQuery()\n    .processInstanceId(processInstanceId).singleResult();\nif (pi != null) {\n    runtimeService.addUserIdentityLink(processInstanceId, userId, IdentityLinkType.PARTICIPANT);\n}","handlingStrategy":"validation","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery()\n    .processInstanceId(processInstanceId).singleResult();\nif (pi == null) {\n    // instance ended or never existed; handle before adding links\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.addUserIdentityLink(piId, userId, type);\n} catch (FlowableObjectNotFoundException e) {\n    if (ExecutionEntity.class.equals(e.getObjectClass())) {\n        // process instance not in runtime: fall back to historic API or report stale id\n    }\n    throw e;\n}","preventionTips":["Always obtain the id from ProcessInstance.getId() rather than task/historic ids.","Check the instance exists (and is not suspended/ended) before mutating runtime state.","Clean up or archive stale stored instance ids when instances complete."],"tags":["flowable","process-instance","not-found","execution"],"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"}