flowable/flowable-engine · error · FlowableIllegalArgumentException

The business status is mandatory, but 'null' has been…

Error message

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

What it means

Constructor validation in SetProcessInstanceBusinessStatusCmd: processInstanceId was fine but the businessStatus argument is null/empty. Since setting an empty status is meaningless, the command is rejected at construction with the offending value interpolated in the message.

Solutions

1. Pass a non-null status string (use "" if a blank status is intended).
2. Validate/normalize the status field in the DTO before the service call.
3. If the goal is to remove the status, set an empty string instead of null.

Example fix

// before
runtimeService.setProcessInstanceBusinessStatus(id, businessStatus); // null
// after
runtimeService.setProcessInstanceBusinessStatus(id, businessStatus == null ? "" : businessStatus);

if (businessStatus == null) {
    throw new IllegalArgumentException("businessStatus is required; use \"\" to clear");
}

try {
    runtimeService.setProcessInstanceBusinessStatus(id, status);
} catch (FlowableIllegalArgumentException e) {
    // handle null business status
}

When it happens

Trigger: Calling RuntimeService.setProcessInstanceBusinessStatus(processInstanceId, null).

Common situations: DTO field not populated before the call, or developer assuming null clears the status.

Related errors

• ProcessInstanceId cannot be null.
• ProcessInstanceId cannot be null.
• processInstanceId is null
• processInstanceId is null
• processInstanceId is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/SetProcessInstanceBusinessStatusCmd.java:45

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

    private static final long serialVersionUID = 1L;

    private final String processInstanceId;
    private final String businessStatus;

    public SetProcessInstanceBusinessStatusCmd(String processInstanceId, String businessStatus) {
        if (processInstanceId == null || processInstanceId.isEmpty()) {
            throw new FlowableIllegalArgumentException("The process instance id is mandatory, but '" + processInstanceId + "' has been provided.");
        }
        if (businessStatus == null) {
            throw new FlowableIllegalArgumentException("The business status is mandatory, but 'null' has been provided.");
        }

        this.processInstanceId = processInstanceId;
        this.businessStatus = businessStatus;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        ExecutionEntityManager executionManager = CommandContextUtil.getExecutionEntityManager(commandContext);
        ExecutionEntity processInstance = executionManager.findById(processInstanceId);
        if (processInstance == null) {
            throw new FlowableObjectNotFoundException("No process instance found for id = '" + processInstanceId + "'.", ProcessInstance.class);

        } else if (!processInstance.isProcessInstanceType()) {
            throw new FlowableIllegalArgumentException("A process instance id is required, but the provided id " + "'" + processInstanceId + "' " + "points to a child execution of process instance " + "'"
                    + processInstance.getProcessInstanceId() + "'. " + "Please invoke the " + getClass().getSimpleName() + " with a root execution id.");
        }

View on GitHub (pinned to d6d39ce1c6)