flowable/flowable-engine · error · FlowableException

Must specify a process definition id to migrate

Error message

Must specify a process definition id to migrate

What it means

ProcessInstanceMigrationBatchCmd's (String processDefinitionId, ProcessInstanceMigrationDocument) constructor validates that a target process definition id is provided before starting a batch migration. A null id would leave the batch without a migration target, so Flowable fails fast with a FlowableException.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/ProcessInstanceMigrationBatchCmd.java:34

import org.flowable.batch.api.Batch;
import org.flowable.common.engine.api.FlowableException;
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;

public class ProcessInstanceMigrationBatchCmd implements Command<Batch> {
    
    protected String processDefinitionId;
    protected String processDefinitionKey;
    protected int processDefinitionVersion;
    protected String processDefinitionTenantId;
    protected ProcessInstanceMigrationDocument processInstanceMigrationDocument;

    public ProcessInstanceMigrationBatchCmd(String processDefinitionId, ProcessInstanceMigrationDocument processInstanceMigrationDocument) {
        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");
        }

        this.processDefinitionId = processDefinitionId;
        this.processInstanceMigrationDocument = processInstanceMigrationDocument;
    }

    public ProcessInstanceMigrationBatchCmd(String processDefinitionKey, int processDefinitionVersion, String processDefinitionTenantId,
                    ProcessInstanceMigrationDocument processInstanceMigrationDocument) {

        if (processDefinitionKey == null) {
            throw new FlowableException("Must specify a process definition key to migrate");
        }
        
        if (processInstanceMigrationDocument == null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Resolve a valid process definition id (e.g. repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleResult().getId()) and pass it to the constructor.
2. Null-check the id before constructing the command.
3. If you only have a key/version/tenant, use the key-based constructor instead.

Example fix

// before
new ProcessInstanceMigrationBatchCmd(null, migrationDocument);
// after
ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("myProcess").latestVersion().singleResult();
new ProcessInstanceMigrationBatchCmd(pd.getId(), migrationDocument);

if (processDefinitionId == null || processDefinitionId.isEmpty()) {
    throw new IllegalArgumentException("target process definition id required");
}

String requireId(String id) {
    if (id == null || id.isEmpty()) throw new IllegalArgumentException("definition id required");
    return id;
}

When it happens

Trigger: Constructing new ProcessInstanceMigrationBatchCmd(null, migrationDocument) — passing a null target process definition id.

Common situations: Migration target resolved dynamically (variable/config/DB) and came back null; typo'd variable wiring; refactoring switched from key-based to id-based constructor without updating the caller.

Related errors

• Must specify a process migration document to migrate
• Must specify a process definition key to migrate
• type is null
• status is null
• scopeId is null

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