{"record":{"id":"7f1e69b8e7ae56d7","repo":"flowable/flowable-engine","slug":"the-process-instance-id-is-mandatory-but-proce","errorCode":null,"errorMessage":"The process instance id is mandatory, but '${processInstanceId}' has been provided.","messagePattern":"The process instance id is mandatory, but '(.+?)' has been provided\\.","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java","lineNumber":65,"sourceCode":" * The command will fail, if there is already a {@link ProcessInstance} or {@link HistoricProcessInstance} using the new process definition version and the same business key as the\n * {@link ProcessInstance} that is to be migrated.\n * \n * If the process instance is not currently waiting but actively running, then this would be a case for optimistic locking, meaning either the version update or the \"real work\" wins, i.e., this is a\n * race condition.\n * \n * @see <a href=\"http://forums.activiti.org/en/viewtopic.php?t=2918\">http://forums.activiti.org/en/viewtopic.php?t=2918</a>\n * @author Falko Menge\n */\npublic class SetProcessDefinitionVersionCmd implements Command<Void>, Serializable {\n\n    private static final long serialVersionUID = 1L;\n\n    private final String processInstanceId;\n    private final Integer processDefinitionVersion;\n\n    public SetProcessDefinitionVersionCmd(String processInstanceId, Integer processDefinitionVersion) {\n        if (processInstanceId == null || processInstanceId.length() < 1) {\n            throw new FlowableIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n        if (processDefinitionVersion == null) {\n            throw new FlowableIllegalArgumentException(\"The process definition version is mandatory, but 'null' has been provided.\");\n        }\n        if (processDefinitionVersion < 1) {\n            throw new FlowableIllegalArgumentException(\"The process definition version must be positive, but '\" + processDefinitionVersion + \"' has been provided.\");\n        }\n        this.processInstanceId = processInstanceId;\n        this.processDefinitionVersion = processDefinitionVersion;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        // check that the new process definition is just another version of the same\n        // process definition that the process instance is using\n        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);\n        ExecutionEntity processInstance = executionManager.findById(processInstanceId);\n        if (processInstance == null) {","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L47-L83","documentation":"SetProcessDefinitionVersionCmd's constructor validates that processInstanceId is non-null and non-empty, throwing FlowableIllegalArgumentException otherwise. This is eager constructor-time argument validation: the command instance cannot even be created without a valid process instance id. The message interpolates the offending value (typically the string 'null' or '').","triggerScenarios":"Constructing new SetProcessDefinitionVersionCmd(null, version) or new SetProcessDefinitionVersionCmd(\"\", version), often when the instance id comes from a null return of a runtime service query or an unset variable.","commonSituations":"execution.getProcessInstanceId() returning null in early lifecycle callbacks; empty-string ids produced by broken deserialization; copy-paste passing the wrong variable into the constructor.","solutions":["Verify the process instance exists via RuntimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() before constructing the command","Reject null/empty ids at your own call site before invoking the command","If the id comes from a query result, null-check it first"],"exampleFix":"// before\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, 2));\n// after\nif (instanceId == null || instanceId.isEmpty()) {\n    throw new IllegalStateException(\"processInstanceId is required\");\n}\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, 2));","handlingStrategy":"type-guard","validationCode":"if (processInstanceId == null || processInstanceId.isEmpty()) {\n    throw new IllegalArgumentException(\"processInstanceId required\");\n}","typeGuard":"boolean isValidProcessInstanceId(String id) {\n    return id != null && !id.trim().isEmpty();\n}","tryCatchPattern":"try {\n    managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));\n} catch (FlowableIllegalArgumentException e) {\n    log.error(\"Invalid arguments for SetProcessDefinitionVersionCmd\", e);\n}","preventionTips":["Null-check processInstanceId returned from executions/variables before use","Validate inputs at your service layer boundary","Construct the command only after confirming the instance exists in RuntimeService"],"tags":["flowable","null-argument","validation","process-instance","java"],"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-14T05:17:10.506Z"}