{"record":{"id":"d6b907ae54285c9d","repo":"flowable/flowable-engine","slug":"the-process-instance-id-is-mandatory-but-pro-d6b907","errorCode":null,"errorMessage":"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.","messagePattern":"The process instance id is mandatory, but '\" \\+ processInstanceId \\+ \"' has been provided\\.","errorType":"exception","errorClass":"ActivitiIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessDefinitionVersionCmd.java","lineNumber":61,"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 http://forums.activiti.org/en/viewtopic.php?t=2918\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 ActivitiIllegalArgumentException(\"The process instance id is mandatory, but '\" + processInstanceId + \"' has been provided.\");\n        }\n        if (processDefinitionVersion == null) {\n            throw new ActivitiIllegalArgumentException(\"The process definition version is mandatory, but 'null' has been provided.\");\n        }\n        if (processDefinitionVersion < 1) {\n            throw new ActivitiIllegalArgumentException(\"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 = commandContext.getExecutionEntityManager();\n        ExecutionEntity processInstance = executionManager.findExecutionById(processInstanceId);\n        if (processInstance == null) {","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessDefinitionVersionCmd.java#L43-L79","documentation":"SetProcessDefinitionVersionCmd's constructor validates arguments eagerly: a null or empty processInstanceId throws ActivitiIllegalArgumentException when the command object is built, before it is executed.","triggerScenarios":"new SetProcessDefinitionVersionCmd(null, version) or new SetProcessDefinitionVersionCmd(\"\", version), e.g. via management/CommandExecutor paths that migrate a process instance to a different definition version.","commonSituations":"Process instance id never captured after startProcessInstanceByKey, empty request/script variables, or instance already completed so the reference was cleared.","solutions":["Pass the id from ProcessInstance.getId() (or Execution.getId()) captured at instance start.","Null/empty-check the id at the call site before constructing the command.","Fix the upstream lookup that returns an empty instance id."],"exampleFix":"// before\nmanagementService.executeCommand(new SetProcessDefinitionVersionCmd(processInstanceId, 2));\n// after\nif (processInstanceId != null && !processInstanceId.isEmpty()) {\n    managementService.executeCommand(new SetProcessDefinitionVersionCmd(processInstanceId, 2));\n}","handlingStrategy":"validation","validationCode":"if (processInstanceId == null || processInstanceId.trim().isEmpty()) throw new IllegalArgumentException(\"processInstanceId required\");","typeGuard":null,"tryCatchPattern":"try { managementService.executeCommand(new SetProcessDefinitionVersionCmd(piId, version)); }\ncatch (ActivitiIllegalArgumentException e) { log.error(\"invalid process instance id '{}'\", piId); }","preventionTips":["Capture ProcessInstance.getId() at start time","Validate instance ids before constructing commands","Guard against cleared references after instance completion"],"tags":["process-instance","illegal-argument","validation","empty-string"],"backgroundTag":"empty-required-field","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"}