flowable/flowable-engine · error · ActivitiIllegalArgumentException

The process instance id is mandatory, but '<processInstanceI

Error message

The process instance id is mandatory, but '<processInstanceId>' has been provided.

What it means

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.

Source

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

import org.activiti.engine.impl.persistence.entity.ExecutionEntity;
import org.activiti.engine.impl.persistence.entity.ExecutionEntityManager;
import org.activiti.engine.runtime.ProcessInstance;

/**
 * {@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 " +

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the processInstanceId is non-empty before invoking: throw a descriptive exception in caller code if it is blank.
2. Start the instance first (runtimeService.startProcessInstanceByKey(key, businessKey)) so the id is known, then set the business key if it must change.
3. Trim and check input at the API boundary before reaching the engine.

Example fix

// before
runtimeService.setBusinessKey(request.getProcessInstanceId(), request.getBusinessKey()); // may be ""
// after
if (request.getProcessInstanceId() == null || request.getProcessInstanceId().isBlank()) {
    throw new IllegalArgumentException("processInstanceId must be provided");
}
runtimeService.setBusinessKey(request.getProcessInstanceId(), request.getBusinessKey());

if (pid == null || pid.trim().isEmpty()) {
    throw new IllegalArgumentException("processInstanceId must be a non-empty string");
}

boolean hasId(String pid) { return pid != null && !pid.trim().isEmpty(); }

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

When it happens

Trigger: 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.

Common situations: REST handlers forwarding an empty path/query parameter; beans whose id field was never populated because the instance creation step failed upstream.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• The case definition id is mandatory, but '' has been provide
• variableName is null
• caseInstanceId is null
• version must be positive
• The task definition key is mandatory, but '${taskDefinitionK

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