flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id is required

Error message

Process instance id is required

What it means

When moving or enabling by activity id (rather than by execution id), ChangeActivityStateCmd needs the process instance id to locate the state to change. Flowable throws FlowableIllegalArgumentException if moveActivityIdList or enableActivityIdList is non-empty but processInstanceId was never set on the builder.

Solutions

1. Call .processInstanceId(processInstanceId) on the ChangeActivityStateBuilder before changeState().
2. Alternatively move by execution id (moveExecutionIdTo...) which does not require processInstanceId.
3. Pre-validate that processInstanceId is set whenever move/enable activity ids are used.

Example fix

// before
runtimeService.createChangeActivityStateBuilder()
    .moveActivityIdTo("task1", "task2").changeState();
// after
runtimeService.createChangeActivityStateBuilder()
    .processInstanceId(processInstanceId)
    .moveActivityIdTo("task1", "task2").changeState();

if ((moveActivityIds.size() > 0 || enableActivityIds.size() > 0) && processInstanceId == null) {
    throw new IllegalArgumentException("processInstanceId is required for activity-id based moves");
}

When it happens

Trigger: runtimeService.createChangeActivityStateBuilder().moveActivityIdTo("a","b").changeState() without calling processInstanceId(...); same for enableActivity(...) without a process instance id.

Common situations: Using activity-id based movement but forgetting the builder's processInstanceId() call; copying execution-id based examples (which don't need the id) and switching to activity ids.

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

• No move execution or activity ids or enable activity ids…
• A process instance id is required, but the provided id '" +…
• A process instance id is required, but the provided id
• Cannot add a comment to a suspended
• Cannot create 'script' task listener. Missing ScriptInfo.

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ChangeActivityStateCmd.java:42

 * @author Tijs Rademakers
 */
public class ChangeActivityStateCmd implements Command<Void> {

    protected ChangeActivityStateBuilderImpl changeActivityStateBuilder;

    public ChangeActivityStateCmd(ChangeActivityStateBuilderImpl changeActivityStateBuilder) {
        this.changeActivityStateBuilder = changeActivityStateBuilder;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        if (changeActivityStateBuilder.getMoveExecutionIdList().isEmpty() && changeActivityStateBuilder.getMoveActivityIdList().isEmpty()
                && changeActivityStateBuilder.getEnableActivityIdList().isEmpty()) {
            
            throw new FlowableIllegalArgumentException("No move execution or activity ids or enable activity ids provided");

        } else if ((!changeActivityStateBuilder.getMoveActivityIdList().isEmpty() || !changeActivityStateBuilder.getEnableActivityIdList().isEmpty()) && changeActivityStateBuilder.getProcessInstanceId() == null) {
            throw new FlowableIllegalArgumentException("Process instance id is required");
        }

        DynamicStateManager dynamicStateManager = CommandContextUtil.getProcessEngineConfiguration(commandContext).getDynamicStateManager();
        dynamicStateManager.moveExecutionState(changeActivityStateBuilder, commandContext);

        return null;
    }
}

View on GitHub (pinned to d6d39ce1c6)