{"record":{"id":"32144448da40cb07","repo":"flowable/flowable-engine","slug":"cannot-find-processinstance-for-id-processinstan","errorCode":null,"errorMessage":"Cannot find processInstance for id '{processInstanceId}'.","messagePattern":"Cannot find processInstance for id '(.+?)'\\.","errorType":"exception","errorClass":"FlowableObjectNotFoundException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java","lineNumber":64,"sourceCode":"    protected final String processInstanceId;\r\n\r\n    public AbstractSetProcessInstanceStateCmd(String processInstanceId) {\r\n        this.processInstanceId = processInstanceId;\r\n    }\r\n\r\n    @Override\r\n    public Void execute(CommandContext commandContext) {\r\n\r\n        if (processInstanceId == null) {\r\n            throw new FlowableIllegalArgumentException(\"ProcessInstanceId cannot be null.\");\r\n        }\r\n\r\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\r\n        ExecutionEntityManager executionEntityManager = processEngineConfiguration.getExecutionEntityManager();\r\n        ExecutionEntity executionEntity = executionEntityManager.findById(processInstanceId);\r\n\r\n        if (executionEntity == null) {\r\n            throw new FlowableObjectNotFoundException(\"Cannot find processInstance for id '\" + processInstanceId + \"'.\", Execution.class);\r\n        }\r\n        if (!executionEntity.isProcessInstanceType()) {\r\n            throw new FlowableException(\"Cannot set suspension state for execution '\" + executionEntity + \"': not a process instance.\");\r\n        }\r\n\r\n        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, executionEntity.getProcessDefinitionId())) {\r\n            if (getNewState() == SuspensionState.ACTIVE) {\r\n                processEngineConfiguration.getFlowable5CompatibilityHandler().activateProcessInstance(processInstanceId);\r\n            } else {\r\n                processEngineConfiguration.getFlowable5CompatibilityHandler().suspendProcessInstance(processInstanceId);\r\n            }\r\n            return null;\r\n        }\r\n\r\n        SuspensionStateUtil.setSuspensionState(executionEntity, getNewState());\r\n        executionEntityManager.update(executionEntity, false);\r\n\r\n        // All child executions are suspended\r","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java#L46-L82","documentation":"FlowableObjectNotFoundException thrown by AbstractSetProcessInstanceStateCmd.execute when no execution entity exists in ACT_RU_EXECUTION for the given processInstanceId. The activate/suspend process instance command looks up the root execution first; if the id is unknown or the instance has ended, it aborts with this error rather than silently succeeding. The exception carries Execution.class as the referenced entity type.","triggerScenarios":"Calling runtimeService.activateProcessInstanceById(id) or suspendProcessInstanceById(id) with an id that does not exist, has been deleted, or references a completed/historic process instance.","commonSituations":"Passing a processDefinitionId instead of a processInstanceId; storing ids across a database reset; operating on an instance that finished between fetch and activation; typos or stale ids from external persistence.","solutions":["Verify the id is a real process instance id: runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() != null.","Use the result of runtimeService.startProcessInstanceByKey(...) directly instead of reconstructing the id.","If the instance already ended, use HistoryService to inspect it rather than changing suspension state.","Check you are not swapping processDefinitionId/processInstanceId arguments; use suspendProcessInstanceByKey for definition-level suspension."],"exampleFix":"// before\nruntimeService.suspendProcessInstanceById(processDefinitionId);\n// after\nProcessInstance pi = runtimeService.createProcessInstanceQuery()\n    .processInstanceId(processInstanceId).singleResult();\nif (pi != null) {\n    runtimeService.suspendProcessInstanceById(pi.getId());\n}","handlingStrategy":"try-catch","validationCode":"if (runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() == null) {\n    throw new IllegalArgumentException(\"Unknown process instance: \" + id);\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.suspendProcessInstanceById(id);\n} catch (FlowableObjectNotFoundException e) {\n    // instance missing or already ended; log and continue\n}","preventionTips":["Always derive ids from startProcessInstance* return values.","Distinguish processDefinitionId from processInstanceId.","Treat finished instances as history-only.","Query before mutating in long-running jobs."],"tags":["flowable","process-instance","not-found","suspension"],"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"}