{"record":{"id":"0686b996bd9e9a4f","repo":"flowable/flowable-engine","slug":"the-process-instance-id-is-mandatory-but-proces","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/SetProcessInstanceBusinessKeyCmd.java","lineNumber":40,"sourceCode":"import org.activiti.engine.impl.persistence.entity.ExecutionEntity;\nimport org.activiti.engine.impl.persistence.entity.ExecutionEntityManager;\nimport org.activiti.engine.runtime.ProcessInstance;\n\n/**\n * {@link Command} that changes the business key of an existing process instance.\n * \n * @author Tijs Rademakers\n */\npublic class SetProcessInstanceBusinessKeyCmd implements Command<Void>, Serializable {\n\n    private static final long serialVersionUID = 1L;\n\n    private final String processInstanceId;\n    private final String businessKey;\n\n    public SetProcessInstanceBusinessKeyCmd(String processInstanceId, String businessKey) {\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 (businessKey == null) {\n            throw new ActivitiIllegalArgumentException(\"The business key is mandatory, but 'null' has been provided.\");\n        }\n\n        this.processInstanceId = processInstanceId;\n        this.businessKey = businessKey;\n    }\n\n    @Override\n    public Void execute(CommandContext commandContext) {\n        ExecutionEntityManager executionManager = commandContext.getExecutionEntityManager();\n        ExecutionEntity processInstance = executionManager.findExecutionById(processInstanceId);\n        if (processInstance == null) {\n            throw new ActivitiObjectNotFoundException(\"No process instance found for id = '\" + processInstanceId + \"'.\", ProcessInstance.class);\n        } else if (!processInstance.isProcessInstanceType()) {\n            throw new ActivitiIllegalArgumentException(\n                    \"A process instance id is required, but the provided id \" +","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java#L22-L58","documentation":"SetProcessInstanceBusinessKeyCmd sets/updates the businessKey of a running process instance. Its constructor requires a non-null, non-empty processInstanceId and throws ActivitiIllegalArgumentException when the check `processInstanceId == null || length() < 1` fails.","triggerScenarios":"runtimeService.setBusinessKey(null or \"\", businessKey) — e.g. the id came from an empty optional, an unset request parameter, or a trimmed string that ended up empty.","commonSituations":"REST handlers forwarding an empty path/query parameter; beans whose id field was never populated because the instance creation step failed upstream.","solutions":["Ensure the processInstanceId is non-empty before invoking: throw a descriptive exception in caller code if it is blank.","Start the instance first (runtimeService.startProcessInstanceByKey(key, businessKey)) so the id is known, then set the business key if it must change.","Trim and check input at the API boundary before reaching the engine."],"exampleFix":"// before\nruntimeService.setBusinessKey(request.getProcessInstanceId(), request.getBusinessKey()); // may be \"\"\n// after\nif (request.getProcessInstanceId() == null || request.getProcessInstanceId().isBlank()) {\n    throw new IllegalArgumentException(\"processInstanceId must be provided\");\n}\nruntimeService.setBusinessKey(request.getProcessInstanceId(), request.getBusinessKey());","handlingStrategy":"validation","validationCode":"if (pid == null || pid.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"processInstanceId must be a non-empty string\");\n}","typeGuard":"boolean hasId(String pid) { return pid != null && !pid.trim().isEmpty(); }","tryCatchPattern":"try {\n    runtimeService.setBusinessKey(pid, key);\n} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {\n    // pid null/empty\n}","preventionTips":["Trim and validate path/query parameters at the API boundary","Only call engine APIs after instance creation succeeded and an id is confirmed"],"tags":["java","flowable","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-14T11:17:12.474Z"}