What causes "Cannot validate process migration, not enough information" in flowable/flowable-engine?

Set exactly one selector: a processInstanceId, a processDefinitionId, or key+version (version >= 0)

flowable/flowable-engine · error · FlowableException

Cannot validate process migration, not enough information

Error message

Cannot validate process migration, not enough information

What it means

In ProcessInstanceMigrationValidationCmd.execute, validation can target a process instance id, a process definition id, or a definition key+version. If none of these selectors is populated the command cannot determine what to validate and throws this FlowableException. It means the validation command was executed with no migration target set.

Solutions

Set exactly one selector: a processInstanceId, a processDefinitionId, or key+version (version >= 0)
Use the public API: managementService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(...).validateMigration(...) which populates the selector
Check that version is not left at its unset default when migrating by key

Example fix

// before
ProcessInstanceMigrationValidationCmd cmd = new ProcessInstanceMigrationValidationCmd(doc); // no target
// after
ProcessInstanceMigrationValidationCmd cmd = new ProcessInstanceMigrationValidationCmd(
    doc, processDefinitionId);

Defensive patterns

Strategy: validation

Validate before calling

boolean hasValidationTarget = instanceId != null
    || definitionId != null
    || (definitionKey != null && definitionVersion >= 0);
if (!hasValidationTarget) throw new IllegalArgumentException("Set a validation target");

Type guard

boolean hasTarget(ProcessInstanceMigrationValidationCmd cmd) { return cmd != null; }

Try / catch

try {
    validationCmd.execute(commandContext);
} catch (FlowableException e) {
    if (e.getMessage().contains("Cannot validate process migration")) {
        throw new IllegalStateException("No validation selector set", e);
    }
    throw e;
}

Prevention

Always validate via the builder: ...migrateToProcessDefinition(...).validateMigration(...)
Check that key-based targeting includes a version >= 0
Add a smoke test that validates a sample migration end-to-end

When it happens

Trigger: Executing a ProcessInstanceMigrationValidationCmd constructed without setting processInstanceId, processDefinitionId, or (processDefinitionKey + processDefinitionVersion >= 0) — e.g. only the document was provided, or key was set but version remained the default -1.

Common situations: Custom validation tooling instantiating the command directly; constructor arguments dropped during refactoring; key set but version left unset; mixing constructor variants so no selector survives.

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

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

Appendix: source

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

    @Override
    public ProcessInstanceMigrationValidationResult execute(CommandContext commandContext) {

        ProcessInstanceMigrationManager migrationManager = CommandContextUtil.getProcessEngineConfiguration(commandContext).getProcessInstanceMigrationManager();

        if (processInstanceId != null) {
            return migrationManager.validateMigrateProcessInstance(processInstanceId, processInstanceMigrationDocument, commandContext);
        }

        if (processDefinitionId != null) {
            return migrationManager.validateMigrateProcessInstancesOfProcessDefinition(processDefinitionId, processInstanceMigrationDocument, commandContext);
        }

        if (processDefinitionKey != null && processDefinitionVersion >= 0) {
            return migrationManager.validateMigrateProcessInstancesOfProcessDefinition(processDefinitionKey, processDefinitionVersion, processDefinitionTenantId, processInstanceMigrationDocument, commandContext);
        }

        throw new FlowableException("Cannot validate process migration, not enough information");
    }

}

View on GitHub (pinned to d6d39ce1c6)