{"record":{"id":"3ca3644ad5595a42","repo":"flowable/flowable-engine","slug":"cannot-find-process-instance-with-id-processinst-3ca364","errorCode":null,"errorMessage":"Cannot find process instance with id ${processInstanceId}","messagePattern":"Cannot find process instance with id (.+?)","errorType":"exception","errorClass":"ActivitiObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java","lineNumber":68,"sourceCode":"        }\n\n        if (type == null) {\n            throw new ActivitiIllegalArgumentException(\"type is required when adding a new process instance identity link\");\n        }\n\n        if (userId == null && groupId == null) {\n            throw new ActivitiIllegalArgumentException(\"userId and groupId cannot both be null\");\n        }\n\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n\n        ExecutionEntity processInstance = commandContext.getExecutionEntityManager().findExecutionById(processInstanceId);\n\n        if (processInstance == null) {\n            throw new ActivitiObjectNotFoundException(\"Cannot find process instance with id \" + processInstanceId, ExecutionEntity.class);\n        }\n\n        processInstance.addIdentityLink(userId, groupId, type);\n\n        commandContext.getHistoryManager().createProcessInstanceIdentityLinkComment(processInstanceId, userId, groupId, type, true);\n\n        return null;\n\n    }\n\n}\n","sourceCodeStart":50,"sourceCodeEnd":80,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AddIdentityLinkForProcessInstanceCmd.java#L50-L80","documentation":"In execute, AddIdentityLinkForProcessInstanceCmd fetches the execution via ExecutionEntityManager.findExecutionById(processInstanceId). If no execution exists for the id, Flowable throws ActivitiObjectNotFoundException (message includes the id, carrying ExecutionEntity.class) so callers can distinguish a missing instance from other failures.","triggerScenarios":"Calling runtimeService.addUserIdentityLinkForProcessInstance with an id of a process instance that has already ended (history moved the execution), was never started, or belongs to a different database/tenant.","commonSituations":"Race condition where the process finished between fetching the id and adding the link; using a historic process instance id on the runtime service; test/prod database mismatch.","solutions":["Check the instance exists first: runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult()","Handle completed instances via the history service (HistoricProcessInstance) instead of adding runtime links","Confirm the id and the datasource/tenant configuration point to the same environment"],"exampleFix":"// before\nruntimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type); // instance ended\n// after\nProcessInstance pi = runtimeService.createProcessInstanceQuery()\n    .processInstanceId(pid).singleResult();\nif (pi != null) {\n    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);\n} else {\n    // fall back to historyService for ended instances\n}","handlingStrategy":"try-catch","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery()\n    .processInstanceId(pid).singleResult();\nif (pi == null) {\n    throw new IllegalStateException(\"Process instance not running: \" + pid);\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.addUserIdentityLinkForProcessInstance(pid, userId, null, type);\n} catch (ActivitiObjectNotFoundException e) {\n    if (ExecutionEntity.class.equals(e.getObjectClass())) {\n        // instance completed or never existed; use historyService instead\n    } else { throw e; }\n}","preventionTips":["Query the runtime for the instance before linking","Treat finished instances as history-domain data, not runtime data","Watch for completion races in asynchronous workflows"],"tags":["not-found","process-instance","identity-link","runtime"],"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-18T11:17:12.947Z"}