{"record":{"id":"706c675835cdd55c","repo":"flowable/flowable-engine","slug":"no-process-instance-found-for-id-processins","errorCode":null,"errorMessage":"No process instance found for id = '\" + processInstanceId + \"'.\"","messagePattern":"No process instance found for id = '\" \\+ processInstanceId \\+ \"'\\.\"","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceClaimCmd.java","lineNumber":57,"sourceCode":"\n    private final String processInstanceId;\n    private final String userId;\n\n    public ProcessInstanceClaimCmd(String processInstanceId, String userId) {\n        if (processInstanceId == null || processInstanceId.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n\n        this.processInstanceId = processInstanceId;\n        this.userId = userId;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);\n        ExecutionEntity processInstance = executionManager.findById(processInstanceId);\n        if (processInstance == null) {\n            throw new FlowableObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\n\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new FlowableIllegalArgumentException(\"A process instance id is required, but the provided id \" + \"'\" + processInstanceId + \"' \" + \"points to a child execution of process instance \" + \"'\"\n                    + processInstance.getProcessInstanceId() + \"'. \" + \"Please invoke the \" + getClass().getSimpleName() + \" with a root execution id.\");\n        }\n\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        if (userId != null) {\n            List<IdentityLinkEntity> identityLinks = processEngineConfiguration.getIdentityLinkServiceConfiguration()\n                    .getIdentityLinkService().findIdentityLinksByProcessInstanceId(processInstanceId);\n            for (IdentityLinkEntity identityLink : identityLinks) {\n                if (IdentityLinkType.ASSIGNEE.equals(identityLink.getType())) {\n                    throw new FlowableException(\"Process instance '\" + processInstanceId + \"' is already claimed.\");\n                }\n            }\n\n            IdentityLinkUtil.createProcessInstanceIdentityLink(processInstance, userId, null, IdentityLinkType.ASSIGNEE);\n","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceClaimCmd.java#L39-L75","documentation":"ProcessInstanceClaimCmd looks up the execution by id and throws FlowableObjectNotFoundException when no execution entity exists for the given processInstanceId. Because claims attach identity links to the process instance's root execution, a missing id means nothing can be claimed.","triggerScenarios":"Executing ProcessInstanceClaimCmd with a processInstanceId that has no row in ACT_RU_EXECUTION — never started, already ended, or from another database.","commonSituations":"Claiming an instance after it completed (runtime rows removed, only history remains); id from a different environment/schema; typo or truncated id from logs.","solutions":["Confirm the instance exists and is running: runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult().","If the instance already ended, use history APIs (HistoryService.createHistoricProcessInstanceQuery()) instead of claiming.","Verify the datasource/schema matches the environment where the instance was started.","Catch FlowableObjectNotFoundException and return a not-found response to the client."],"exampleFix":"// before\nmanagementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));\n// after\nProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(pid).singleResult();\nif (pi != null) {\n    managementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));\n}","handlingStrategy":"validation","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(pid).singleResult();\nif (pi == null) { throw new NotFoundException(\"Process instance \" + pid + \" not found or already ended\"); }","typeGuard":"boolean runningInstanceExists(String pid) {\n    return pid != null && runtimeService.createProcessInstanceQuery().processInstanceId(pid).count() > 0;\n}","tryCatchPattern":"try {\n    managementService.executeCommand(new ProcessInstanceClaimCmd(pid, userId));\n} catch (FlowableObjectNotFoundException e) {\n    throw new NotFoundException(\"Process instance not found\");\n}","preventionTips":["Check ProcessInstanceQuery before claim/unclaim operations.","Route claims for ended instances to HistoryService-based flows.","Keep environment datasources aligned so ids are looked up in the right DB.","Log and validate instance ids from client payloads."],"tags":["flowable","process-instance","not-found"],"backgroundTag":"record-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"}