{"record":{"id":"726d6ae0ff4a1543","repo":"flowable/flowable-engine","slug":"the-process-definition-version-is-mandatory-but","errorCode":null,"errorMessage":"The process definition version is mandatory, but 'null' has been provided.","messagePattern":"The process definition version is mandatory, but 'null' 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":68,"sourceCode":" * 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) {\n            throw new FlowableObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new FlowableIllegalArgumentException(\"A process instance id is required, but the provided id \" + \"'\" + processInstanceId + \"' \" + \"points to a child execution of process instance \" + \"'\"","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L50-L86","documentation":"SetProcessDefinitionVersionCmd's constructor throws this FlowableIllegalArgumentException when processDefinitionVersion is null. Both arguments are mandatory and validated up front; a null version means the command cannot determine which definition version to migrate the instance to. The constructor fails before any state is assigned.","triggerScenarios":"Constructing new SetProcessDefinitionVersionCmd(processInstanceId, null), typically when the version was read from an unset Integer variable, an absent config field, or the result of an unboxing/null return from a query.","commonSituations":"Integer processDefinitionVersion = map.get(\"version\") returning null when the key is missing; autoboxing null from a database column; refactoring replaced a literal with a nullable variable.","solutions":["Resolve the version explicitly (e.g. from RepositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getVersion()) before constructing the command","Null-check the version at your call site and fail with a clear message","Provide a sensible default version if the business case allows"],"exampleFix":"// before\nInteger version = config.get(\"targetVersion\"); // may be null\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));\n// after\nProcessDefinition def = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"order\").latestVersion().singleResult();\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, def.getVersion()));","handlingStrategy":"type-guard","validationCode":"if (processDefinitionVersion == null || processDefinitionVersion < 1) {\n    throw new IllegalArgumentException(\"processDefinitionVersion must be a positive integer\");\n}","typeGuard":"boolean isValidVersion(Integer version) {\n    return version != null && version >= 1;\n}","tryCatchPattern":"try {\n    managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));\n} catch (FlowableIllegalArgumentException e) {\n    log.error(\"Invalid process definition version argument\", e);\n}","preventionTips":["Fetch the version from ProcessDefinitionEntity.getVersion() instead of nullable maps/config","Use Integer explicitly and check for null before passing","Avoid autoboxing null database values into the version parameter"],"tags":["flowable","null-argument","validation","process-definition","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-14T11:17:12.474Z"}