flowable/flowable-engine · error · FlowableIllegalArgumentException

ProcessInstanceId cannot be null.

Error message

ProcessInstanceId cannot be null.

What it means

execute() of AbstractSetProcessInstanceStateCmd (suspend/activate a process instance) rejects a null processInstanceId with FlowableIllegalArgumentException before touching the execution entity. The command needs a concrete process instance to act on.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/AbstractSetProcessInstanceStateCmd.java:56

import org.flowable.task.service.impl.persistence.entity.TaskEntity;

/**
 * @author Joram Barrez
 * @author Tijs Rademakers
 */
public abstract class AbstractSetProcessInstanceStateCmd implements Command<Void> {

    protected final String processInstanceId;

    public AbstractSetProcessInstanceStateCmd(String processInstanceId) {
        this.processInstanceId = processInstanceId;
    }

    @Override
    public Void execute(CommandContext commandContext) {

        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("ProcessInstanceId cannot be null.");
        }

        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);
        ExecutionEntityManager executionEntityManager = processEngineConfiguration.getExecutionEntityManager();
        ExecutionEntity executionEntity = executionEntityManager.findById(processInstanceId);

        if (executionEntity == null) {
            throw new FlowableObjectNotFoundException("Cannot find processInstance for id '" + processInstanceId + "'.", Execution.class);
        }
        if (!executionEntity.isProcessInstanceType()) {
            throw new FlowableException("Cannot set suspension state for execution '" + executionEntity + "': not a process instance.");
        }

        if (Flowable5Util.isFlowable5ProcessDefinitionId(commandContext, executionEntity.getProcessDefinitionId())) {
            if (getNewState() == SuspensionState.ACTIVE) {
                processEngineConfiguration.getFlowable5CompatibilityHandler().activateProcessInstance(processInstanceId);
            } else {
                processEngineConfiguration.getFlowable5CompatibilityHandler().suspendProcessInstance(processInstanceId);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the processInstanceId is set from runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult() (non-null) before suspending/activating
2. Add a caller-side null/blank check before invoking the management service
3. Fix upstream data flow so the id variable is populated

Example fix

// before
String pid = findInstanceId(orderRef); // may return null
managementService.suspendProcessInstance(pid);
// after
String pid = findInstanceId(orderRef);
if (pid != null) {
    managementService.suspendProcessInstance(pid);
}

if (processInstanceId == null || processInstanceId.isBlank()) {
    throw new IllegalArgumentException("processInstanceId is required");
}

try {
    managementService.suspendProcessInstance(pid);
} catch (FlowableIllegalArgumentException e) {
    // pid was null/blank: fix upstream id resolution
}

When it happens

Trigger: Calling managementService.suspendProcessInstance(null) / activateProcessInstance(null), or building the command with the instance id left unset (e.g. a variable that was null at call time).

Common situations: Instance id taken from a previous lookup that returned null and was passed along; optional id field in a request object left empty.

Related errors

• The process instance id is mandatory, but '${processInstance
• Error retrieving app engine info
• No deployment id available
• No resource name available
• appsDefinitionIds is null

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