{"record":{"id":"a7d407c7e418f1c4","repo":"flowable/flowable-engine","slug":"the-business-key-is-mandatory-but-null-has-been-a7d407","errorCode":null,"errorMessage":"The business key is mandatory, but 'null' has been provided.","messagePattern":"The business key is mandatory, but 'null' 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":43,"sourceCode":"\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 \" +\n                            \"'\" + processInstanceId + \"' \" +\n                            \"points to a child execution of process instance \" +\n                            \"'\" + processInstance.getProcessInstanceId() + \"'. \" +","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java#L25-L61","documentation":"The constructor also validates the businessKey and throws ActivitiIllegalArgumentException when it is null. The business key is a required correlation attribute on the process instance, so the command refuses null rather than silently clearing an existing key.","triggerScenarios":"runtimeService.setBusinessKey(pid, null) — commonly because the key came from a nullable DTO field, a missing header, or a lookup that returned null.","commonSituations":"Integrations where the external correlation id is optional upstream but mandatory in the engine; map/JSON deserialization omitting the businessKey property.","solutions":["Provide a real business key; if there is none, consider a generated default (e.g. UUID) rather than null.","Validate at the boundary: reject requests missing businessKey before calling the engine.","If clearing a key is genuinely intended, this command cannot do it — use the appropriate update path or model change instead."],"exampleFix":"// before\nruntimeService.setBusinessKey(pid, dto.getBusinessKey()); // null\n// after\nif (dto.getBusinessKey() == null) {\n    throw new IllegalArgumentException(\"businessKey is required to set on process instance \" + pid);\n}\nruntimeService.setBusinessKey(pid, dto.getBusinessKey());","handlingStrategy":"validation","validationCode":"if (businessKey == null) {\n    throw new IllegalArgumentException(\"businessKey is required\");\n}","typeGuard":"boolean hasKey(String bk) { return bk != null && !bk.isEmpty(); }","tryCatchPattern":"try {\n    runtimeService.setBusinessKey(pid, key);\n} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {\n    // businessKey was null\n}","preventionTips":["Make businessKey a required field in DTOs/REST contracts","Generate a default key (UUID) when none is supplied instead of passing null"],"tags":["java","flowable","argument-validation","null"],"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-18T11:17:12.947Z"}