{"record":{"id":"f5cf9748e2d1a3e6","repo":"flowable/flowable-engine","slug":"processinstanceid-cannot-be-null","errorCode":null,"errorMessage":"ProcessInstanceId cannot be null.","messagePattern":"ProcessInstanceId cannot be null\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java","lineNumber":56,"sourceCode":"import org.flowable.task.service.impl.persistence.entity.TaskEntity;\r\n\r\n/**\r\n * @author Joram Barrez\r\n * @author Tijs Rademakers\r\n */\r\npublic abstract class AbstractSetProcessInstanceStateCmd implements Command<Void> {\r\n\r\n    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","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java#L38-L74","documentation":"execute() of AbstractSetProcessInstanceStateCmd (suspend/activate a process instance) rejects a null processInstanceId with FlowableIllegalArgumentException before touching the execution entity. The command needs a concrete process instance to act on.","triggerScenarios":"Calling managementService.suspendProcessInstance(null) / activateProcessInstance(null), or building the command with the instance id left unset (e.g. a variable that was null at call time).","commonSituations":"Instance id taken from a previous lookup that returned null and was passed along; optional id field in a request object left empty.","solutions":["Ensure the processInstanceId is set from runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() (non-null) before suspending/activating","Add a caller-side null/blank check before invoking the management service","Fix upstream data flow so the id variable is populated"],"exampleFix":"// before\nString pid = findInstanceId(orderRef); // may return null\nmanagementService.suspendProcessInstance(pid);\n// after\nString pid = findInstanceId(orderRef);\nif (pid != null) {\n    managementService.suspendProcessInstance(pid);\n}","handlingStrategy":"validation","validationCode":"if (processInstanceId == null || processInstanceId.isBlank()) {\n    throw new IllegalArgumentException(\"processInstanceId is required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    managementService.suspendProcessInstance(pid);\n} catch (FlowableIllegalArgumentException e) {\n    // pid was null/blank: fix upstream id resolution\n}","preventionTips":["Check processInstanceId non-null/blank at the API boundary","Derive ids from a query that is guaranteed non-null (assert singleResult() != null)","Avoid passing Optional-unwrapped or possibly-null request fields straight into the engine"],"tags":["flowable","null-argument","process-instance","validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}