flowable/flowable-engine · error · FlowableException

Must specify a process instance id to migrate

Error message

Must specify a process instance id to migrate

What it means

ProcessInstanceMigrationValidationCmd validates a migration plan against a specific process instance. Its constructor throws when the processInstanceId argument is null, because validation cannot determine which running instance the migration map applies to. This fail-fast check mirrors the migration command's own precondition.

Solutions

1. Ensure a valid, non-null process instance id is resolved (e.g. from runtimeService.createProcessInstanceQuery()) before validating
2. Use the public API: managementService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(...).validateMigration(processInstanceId)
3. Add a null/empty assertion on the instance id at the call site

Example fix

// before
ProcessInstance pid = query.singleResult(); // may be null
new ProcessInstanceMigrationValidationCmd(pid.getId(), doc); // NPE / throws
// after
ProcessInstance pid = query.singleResult();
if (pid != null) {
    new ProcessInstanceMigrationValidationCmd(pid.getId(), doc);
}

if (processInstanceId == null || processInstanceId.trim().isEmpty()) {
    throw new IllegalArgumentException("processInstanceId is required for validation");
}

boolean isValidInstanceId(String id) { return id != null && !id.trim().isEmpty(); }

try {
    new ProcessInstanceMigrationValidationCmd(instanceId, doc).execute(commandContext);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a process instance id")) {
        // resolve id via runtimeService query and retry once
    }
    throw e;
}

When it happens

Trigger: Calling new ProcessInstanceMigrationValidationCmd(null, document) directly, or invoking a validation API path where the process instance id variable is null (e.g. it was never fetched or a lookup returned null).

Common situations: Id obtained from a query that returned no row and was not null-checked; hardcoded refactoring where the id placeholder was left null; scripting the internal command classes directly instead of managementService.createProcessInstanceMigrationBuilder().validateMigration(...).

Related errors

• Must specify a process definition id to migrate
• Must specify a process migration document to migrate
• appsDefinitionIds is null
• at least one of userId or groups must be provided
• Business status is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationValidationCmd.java:35

import org.flowable.common.engine.impl.interceptor.Command;
import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.engine.impl.util.CommandContextUtil;
import org.flowable.engine.migration.ProcessInstanceMigrationDocument;
import org.flowable.engine.migration.ProcessInstanceMigrationManager;
import org.flowable.engine.migration.ProcessInstanceMigrationValidationResult;

public class ProcessInstanceMigrationValidationCmd implements Command<ProcessInstanceMigrationValidationResult> {
    
    protected String processInstanceId;
    protected String processDefinitionId;
    protected String processDefinitionKey;
    protected int processDefinitionVersion;
    protected String processDefinitionTenantId;
    protected ProcessInstanceMigrationDocument processInstanceMigrationDocument;

    public ProcessInstanceMigrationValidationCmd(String processInstanceId, ProcessInstanceMigrationDocument processInstanceMigrationDocument) {
        if (processInstanceId == null) {
            throw new FlowableException("Must specify a process instance id to migrate");
        }
        
        if (processInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a process migration document to migrate");
        }

        this.processInstanceId = processInstanceId;
        this.processInstanceMigrationDocument = processInstanceMigrationDocument;
    }

    public ProcessInstanceMigrationValidationCmd(ProcessInstanceMigrationDocument processInstanceMigrationDocument, String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new FlowableException("Must specify a process definition id to migrate");
        }
        
        if (processInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a process migration document to migrate");
        }

View on GitHub (pinned to d6d39ce1c6)