flowable/flowable-engine · error · ActivitiIllegalArgumentException

The business key is mandatory, but 'null' has been provided.

Error message

The business key is mandatory, but 'null' has been provided.

What it means

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.

Solutions

1. Provide a real business key; if there is none, consider a generated default (e.g. UUID) rather than null.
2. Validate at the boundary: reject requests missing businessKey before calling the engine.
3. If clearing a key is genuinely intended, this command cannot do it — use the appropriate update path or model change instead.

Example fix

// before
runtimeService.setBusinessKey(pid, dto.getBusinessKey()); // null
// after
if (dto.getBusinessKey() == null) {
    throw new IllegalArgumentException("businessKey is required to set on process instance " + pid);
}
runtimeService.setBusinessKey(pid, dto.getBusinessKey());

if (businessKey == null) {
    throw new IllegalArgumentException("businessKey is required");
}

boolean hasKey(String bk) { return bk != null && !bk.isEmpty(); }

try {
    runtimeService.setBusinessKey(pid, key);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // businessKey was null
}

When it happens

Trigger: runtimeService.setBusinessKey(pid, null) — commonly because the key came from a nullable DTO field, a missing header, or a lookup that returned null.

Common situations: Integrations where the external correlation id is optional upstream but mandatory in the engine; map/JSON deserialization omitting the businessKey property.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• processInstanceId is null
• The process definition version is mandatory, but 'null' has…
• A process instance id is required, but the provided id '" +…
• A process instance id is required, but the provided id
• Cannot use taskIds together with excludeLocalVariables

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/a7d407c7e418f1c4. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cmd/SetProcessInstanceBusinessKeyCmd.java:43

/**
 * {@link Command} that changes the business key of an existing process instance.
 * 
 * @author Tijs Rademakers
 */
public class SetProcessInstanceBusinessKeyCmd implements Command<Void>, Serializable {

    private static final long serialVersionUID = 1L;

    private final String processInstanceId;
    private final String businessKey;

    public SetProcessInstanceBusinessKeyCmd(String processInstanceId, String businessKey) {
        if (processInstanceId == null || processInstanceId.length() < 1) {
            throw new ActivitiIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }
        if (businessKey == null) {
            throw new ActivitiIllegalArgumentException("The business key is mandatory, but 'null' has been provided.");
        }

        this.processInstanceId = processInstanceId;
        this.businessKey = businessKey;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionManager = commandContext.getExecutionEntityManager();
        ExecutionEntity processInstance = executionManager.findExecutionById(processInstanceId);
        if (processInstance == null) {
            throw new ActivitiObjectNotFoundException("No process instance found for id = '" + processInstanceId + "'.", ProcessInstance.class);
        } else if (!processInstance.isProcessInstanceType()) {
            throw new ActivitiIllegalArgumentException(
                    "A process instance id is required, but the provided id " +
                            "'" + processInstanceId + "' " +
                            "points to a child execution of process instance " +
                            "'" + processInstance.getProcessInstanceId() + "'. " +

View on GitHub (pinned to d6d39ce1c6)