{"record":{"id":"98fceb811b86d8e2","repo":"flowable/flowable-engine","slug":"processinstanceid-cannot-be-null-98fceb","errorCode":null,"errorMessage":"ProcessInstanceId cannot be null.","messagePattern":"ProcessInstanceId cannot be null\\.","errorType":"validation","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java","lineNumber":48,"sourceCode":"import org.flowable.job.api.Job;\r\n\r\n/**\r\n * @author Daniel Meyer\r\n * @author Joram Barrez\r\n */\r\npublic abstract class AbstractSetProcessInstanceStateCmd implements Command<Void> {\r\n\r\n    protected final String executionId;\r\n\r\n    public AbstractSetProcessInstanceStateCmd(String executionId) {\r\n        this.executionId = executionId;\r\n    }\r\n\r\n    @Override\r\n    public Void execute(CommandContext commandContext) {\r\n\r\n        if (executionId == null) {\r\n            throw new ActivitiIllegalArgumentException(\"ProcessInstanceId cannot be null.\");\r\n        }\r\n\r\n        ExecutionEntity executionEntity = commandContext.getExecutionEntityManager().findExecutionById(executionId);\r\n\r\n        if (executionEntity == null) {\r\n            throw new ActivitiObjectNotFoundException(\"Cannot find processInstance for id '\" + executionId + \"'.\", Execution.class);\r\n        }\r\n        if (!executionEntity.isProcessInstanceType()) {\r\n            throw new ActivitiException(\"Cannot set suspension state for execution '\" + executionId + \"': not a process instance.\");\r\n        }\r\n\r\n        SuspensionStateUtil.setSuspensionState(executionEntity, getNewState());\r\n\r\n        // All child executions are suspended\r\n        List<ExecutionEntity> childExecutions = commandContext.getExecutionEntityManager().findChildExecutionsByProcessInstanceId(executionId);\r\n        for (ExecutionEntity childExecution : childExecutions) {\r\n            if (!childExecution.getId().equals(executionId)) {\r\n                SuspensionStateUtil.setSuspensionState(childExecution, getNewState());\r","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java#L30-L66","documentation":"AbstractSetProcessInstanceStateCmd.execute validates that an execution (process instance) id was supplied before suspending or activating a process instance. A null id means the operation is impossible, so it throws ActivitiIllegalArgumentException immediately.","triggerScenarios":"Calling RuntimeService.suspendProcessInstanceById(null) or activateProcessInstanceById(null), or building a suspend/activate process instance command programmatically without setting the execution id.","commonSituations":"A variable holding the process instance id was never populated (e.g. upstream lookup returned null); a DTO field left unset; passing the wrong variable (null businessKey instead of instance id).","solutions":["Ensure the process instance id is resolved before calling suspend/activate (e.g. from ProcessInstance.getId() or a runtime query).","Add a caller-side null/empty check on the id before invoking the API.","Check that the variable you pass is actually the process instance id, not the business key or task id."],"exampleFix":"// before\nruntimeService.suspendProcessInstanceById(instanceId); // instanceId may be null\n// after\nif (instanceId == null || instanceId.isEmpty()) { throw new IllegalArgumentException(\"instanceId required\"); }\nruntimeService.suspendProcessInstanceById(instanceId);","handlingStrategy":"type-guard","validationCode":"if (instanceId == null || instanceId.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"processInstanceId is required\");\n}","typeGuard":"boolean hasProcessInstanceId(String id) { return id != null && !id.trim().isEmpty(); }","tryCatchPattern":"try {\n    runtimeService.suspendProcessInstanceById(id);\n} catch (ActivitiIllegalArgumentException e) {\n    if (\"ProcessInstanceId cannot be null.\".equals(e.getMessage())) {\n        logger.error(\"No process instance id supplied\");\n    } else { throw e; }\n}","preventionTips":["Resolve ids from ProcessInstance.getId() objects, never from hand-written strings","Validate parameters at service boundary before calling engine APIs","Avoid conflating businessKey with instance id in DTOs"],"tags":["null-argument","process-instance","validation","activiti"],"backgroundTag":"missing-required-argument","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"}