{"record":{"id":"10f4ef95bf509b3a","repo":"flowable/flowable-engine","slug":"the-process-definition-version-must-be-positive-b","errorCode":null,"errorMessage":"The process definition version must be positive, but '${processDefinitionVersion}' has been provided.","messagePattern":"The process definition version must be positive, 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":71,"sourceCode":" * @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 \" + \"'\"\n                    + processInstance.getProcessInstanceId() + \"'. \" + \"Please invoke the \" + getClass().getSimpleName() + \" with a root execution id.\");\n        }\n","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L53-L89","documentation":"SetProcessDefinitionVersionCmd's constructor validates its inputs before running the command. When the supplied processDefinitionVersion is less than 1 (e.g. 0 or negative), it throws FlowableIllegalArgumentException because process definition versions in Flowable start at 1.","triggerScenarios":"Calling new SetProcessDefinitionVersionCmd(processInstanceId, version) with version = 0, a negative number, or an uninitialized Integer default of 0.","commonSituations":"Passing a zero-initialized version variable from a config or DB record where the version was never populated; integer arithmetic that subtracts from a version; parsing a version string that yields 0.","solutions":["Verify the version value passed to the constructor is >= 1 before constructing the command","Fix the upstream source of the version (DB column, config, API response) so it holds a real version number","If the version is unknown, fetch the current version from the process instance's processDefinitionId instead of guessing"],"exampleFix":"// before\nint version = 0;\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));\n// after\nif (version >= 1) {\n    managementService.executeCommand(new SetProcessDefinitionVersionCmd(instanceId, version));\n}","handlingStrategy":"validation","validationCode":"if (version == null || version < 1) throw new IllegalArgumentException(\"version must be >= 1\");","typeGuard":"boolean isValidVersion(Integer v) { return v != null && v >= 1; }","tryCatchPattern":"try { managementService.executeCommand(new SetProcessDefinitionVersionCmd(id, v)); } catch (FlowableIllegalArgumentException e) { log.error(\"Invalid version argument\", e); }","preventionTips":["Always validate version > 0 before constructing the command","Fetch the version from the deployed ProcessDefinition rather than hand-maintained values","Avoid 0-initialized version variables"],"tags":["validation","process-definition","argument"],"backgroundTag":"value-out-of-range","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"}