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

ProcessInstanceMigrationValidationCmd requires a non-null ProcessInstanceMigrationDocument in all of its constructors. When the document argument is null the constructor throws this FlowableException, since there is no migration mapping to validate. It is a fail-fast check identical to the one in the migration command.

Solutions

1. Create the document with the migration builder: managementService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(...).getProcessInstanceMigrationDocument()
2. If loading the document from JSON, check the parse/build result for null before validating
3. Assert the document reference before constructing the validation command

Example fix

// before
new ProcessInstanceMigrationValidationCmd(instId, maybeDoc); // maybeDoc null
// after
Objects.requireNonNull(maybeDoc, "migration document required");
new ProcessInstanceMigrationValidationCmd(instId, maybeDoc);

if (processInstanceMigrationDocument == null) {
    throw new IllegalArgumentException("ProcessInstanceMigrationDocument is required");
}

boolean hasMigrationDoc(ProcessInstanceMigrationDocument d) { return d != null; }

try {
    validationCmd.execute(commandContext);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a process migration document")) {
        doc = migrationBuilder.getProcessInstanceMigrationDocument();
    }
    throw e;
}

When it happens

Trigger: Invoking new ProcessInstanceMigrationValidationCmd(processInstanceId, null) or any other validation constructor with a null document — typically because the document build/parse step produced null.

Common situations: Deserializing a migration document JSON that failed silently and returned null; a builder chain short-circuited; passing an uninitialized field; calling the internal command classes directly in tests with placeholder nulls.

Related errors

• Must specify a process definition id to migrate
• Must specify a process instance id 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/2672035bdafd06ab. Report an issue: GitHub.

Appendix: source

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

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");
        }

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

View on GitHub (pinned to d6d39ce1c6)