{"record":{"id":"30c2ef51955955b7","repo":"flowable/flowable-engine","slug":"the-process-instance-with-id-processinstanceid","errorCode":null,"errorMessage":"The process instance with id '{processInstanceId}' could not be found as an active process instance.","messagePattern":"The process instance with id '(.+?)' could not be found as an active process instance\\.","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessInstanceIdentityLinkCmd.java","lineNumber":38,"sourceCode":"\n/**\n * An abstract command supporting functionality around identity link management for process instances.\n *\n * @author Micha Kiener\n */\npublic abstract class AbstractProcessInstanceIdentityLinkCmd {\n\n    /**\n     * Returns the process instance entity for the given id, if it exists, otherwise an exception will be thrown.\n     *\n     * @param commandContext the command context within which the process instance is loaded\n     * @param processInstanceId the id of the process instance to be loaded\n     * @return the process instance entity, if found, never null\n     * @throws FlowableIllegalArgumentException if the provided process instance id is not valid\n     */\n    protected ExecutionEntity getProcessInstanceEntity(CommandContext commandContext, String processInstanceId) {\n        ExecutionEntity processInstance = CommandContextUtil.getExecutionEntityManager(commandContext).findById(processInstanceId);\n        if (processInstance == null) {\n            throw new FlowableIllegalArgumentException(\n                \"The process instance with id '\" + processInstanceId + \"' could not be found as an active process instance.\");\n        }\n        return processInstance;\n    }\n\n    /**\n     * This will remove ALL identity links with the given type, no mather whether they are user or group based.\n     *\n     * @param commandContext the command context within which to remove the identity links\n     * @param processInstanceId the id of the process instance to remove the identity links for\n     * @param identityType the identity link type (e.g. assignee or owner, etc) to be removed\n     */\n    protected void removeIdentityLinkType(CommandContext commandContext, String processInstanceId, String identityType) {\n        ExecutionEntity processInstanceEntity = getProcessInstanceEntity(commandContext, processInstanceId);\n\n        // this will remove ALL identity links with the given identity type (for users AND groups)\n        IdentityLinkUtil.deleteProcessInstanceIdentityLinks(processInstanceEntity, null, null, identityType);","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractProcessInstanceIdentityLinkCmd.java#L20-L56","documentation":"AbstractProcessInstanceIdentityLinkCmd.getProcessInstanceEntity loads the execution by id and, when nothing is found, throws FlowableIllegalArgumentException stating the id could not be found as an active process instance. Identity-link commands (add/remove user or group links on a process instance) require an existing process instance execution.","triggerScenarios":"Calling addUserIdentityLinkToProcessInstance / addGroupIdentityLinkToProcessInstance (or remove equivalents) with a processInstanceId that matches no execution row — deleted/completed instance, typo, wrong id (e.g. task id or process definition id), or wrong database.","commonSituations":"Adding an identity link after the process already ended; passing a historic process instance id to the runtime API; id copied from a different environment; application passed the wrong variable from a form or request.","solutions":["Verify the processInstanceId refers to a live runtime process instance before calling the identity link API.","If the process may have finished, handle the error or check runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() != null first.","Correct the id source (use the actual process instance id, not task/case/definition id)."],"exampleFix":"// before\nruntimeService.addUserIdentityLinkToProcessInstance(processInstanceId, \"john\", \"participant\");\n// after\nif (runtimeService.createProcessInstanceQuery().processInstanceId(processInstanceId).count() > 0) {\n    runtimeService.addUserIdentityLinkToProcessInstance(processInstanceId, \"john\", \"participant\");\n}","handlingStrategy":"validation","validationCode":"if (runtimeService.createProcessInstanceQuery().processInstanceId(processInstanceId).count() == 0) {\n    throw new IllegalArgumentException(\"No active process instance \" + processInstanceId);\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.addUserIdentityLinkToProcessInstance(piId, userId, type);\n} catch (FlowableIllegalArgumentException e) {\n    // instance not active: check historic data instead\n}","preventionTips":["Verify the instance is active before identity-link mutations","Distinguish runtime vs historic ids in your data model","Don't call runtime APIs for ended instances"],"tags":["flowable","identity-link","process-instance","not-found"],"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"}