flowable/flowable-engine · error · FlowableException

Must specify a process migration document to migrate

Error message

Must specify a process migration document to migrate

What it means

ProcessInstanceMigrationBatchCmd requires a non-null ProcessInstanceMigrationDocument describing the migration plan. The (processDefinitionId, document) constructor throws this FlowableException when the document is null, because without a plan there is nothing to migrate.

Source

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

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) {
            throw new FlowableException("Must specify a process migration document to migrate");
        }

        this.processDefinitionKey = processDefinitionKey;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Build the document first, e.g. processInstanceMigrationBuilder.migrateTo(processDefinitionId).addActivityMigrationMapping(...).build(), then pass it.
2. Null-check the document before constructing the command.
3. If the document is loaded from config/JSON, validate it parsed successfully before use.

Example fix

// before
new ProcessInstanceMigrationBatchCmd(processDefinitionId, null);
// after
ProcessInstanceMigrationDocument doc = processInstanceMigrationBuilder
    .migrateTo(processDefinitionId)
    .addActivityMigrationMapping("oldActivity", "newActivity")
    .build();
new ProcessInstanceMigrationBatchCmd(processDefinitionId, doc);

if (migrationDocument == null) {
    throw new IllegalArgumentException("migration document required");
}

When it happens

Trigger: Calling new ProcessInstanceMigrationBatchCmd(processDefinitionId, null) — the migration document was not built or a builder call returned null.

Common situations: Forgetting to call .build() or a factory like processInstanceMigrationBuilder.migrateTo(...); a helper that conditionally builds the document returned null; deserialization of the migration document failed silently.

Related errors

• Must specify a process definition id 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/4449cda175161472. Report an issue: GitHub.