{"record":{"id":"00f6b3de76691ef8","repo":"flowable/flowable-engine","slug":"process-instance-processinstanceid-is-suspended","errorCode":null,"errorMessage":"process instance ${processInstanceId} is suspended, cannot set name","messagePattern":"process instance (.+?) is suspended, cannot set name","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceNameCmd.java","lineNumber":69,"sourceCode":"                Flowable5CompatibilityHandler compatibilityHandler = Flowable5Util.getFlowable5CompatibilityHandler();\n                if (compatibilityHandler != null) {\n                    ProcessInstance processInstance = compatibilityHandler.getProcessInstance(processInstanceId);\n                    if (processInstance != null) {\n                        compatibilityHandler.setProcessInstanceName(processInstance.getId(), name);\n                        return null;\n                    }\n                }\n            }\n            \n            throw new FlowableObjectNotFoundException(\"process instance \" + processInstanceId + \" doesn't exist\", ProcessInstance.class);\n        }\n        \n        if (!execution.isProcessInstanceType()) {\n            throw new FlowableObjectNotFoundException(\"process instance \" + processInstanceId + \" doesn't exist, the given ID references an execution, though\", ProcessInstance.class);\n        }\n\n        if (execution.isSuspended()) {\n            throw new FlowableException(\"process instance \" + processInstanceId + \" is suspended, cannot set name\");\n        }\n\n        // Actually set the name\n        execution.setName(name);\n\n        // Record the change in history\n        CommandContextUtil.getHistoryManager(commandContext).recordProcessInstanceNameChange(execution, name);\n\n        return null;\n    }\n\n}\n","sourceCodeStart":51,"sourceCodeEnd":82,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceNameCmd.java#L51-L82","documentation":"SetProcessInstanceNameCmd refuses to rename a suspended process instance. Flowable suspends instances to freeze them; mutating the name while suspended could conflict with suspension bookkeeping, so the command rejects it with a plain FlowableException.","triggerScenarios":"Calling runtimeService.setProcessInstanceName(id, name) while the instance is suspended via runtimeService.suspendProcessInstanceById(id) or by a suspended process definition.","commonSituations":"Batch renames applied to instances that an administrator suspended for maintenance; instances auto-suspended because their process definition was suspended.","solutions":["Resume the instance first with runtimeService.activateProcessInstanceById(id), set the name, then suspend again if needed.","Skip suspended instances in batch logic, or check runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult().isSuspended() beforehand.","If suspension came from the process definition, evaluate whether the rename is really needed while suspended."],"exampleFix":"// before\nruntimeService.setProcessInstanceName(id, name);\n// after\nruntimeService.activateProcessInstanceById(id);\nruntimeService.setProcessInstanceName(id, name);\nruntimeService.suspendProcessInstanceById(id);","handlingStrategy":"validation","validationCode":"ProcessInstance pi = runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();\nif (pi != null && !pi.isSuspended()) {\n    runtimeService.setProcessInstanceName(id, name);\n}","typeGuard":null,"tryCatchPattern":"try {\n    runtimeService.setProcessInstanceName(id, name);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"is suspended\")) {\n        runtimeService.activateProcessInstanceById(id);\n        runtimeService.setProcessInstanceName(id, name);\n    }\n}","preventionTips":["Check isSuspended() before mutating any suspended instance","In batch jobs, filter out suspended instances via ProcessInstanceQuery.suspended()","Remember definition-level suspension also suspends its instances"],"tags":["flowable","process-instance","suspended","invalid-state"],"backgroundTag":"invalid-state-transition","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"}