flowable/flowable-engine · error · FlowableException

Must specify a process definition key to migrate

Error message

Must specify a process definition key to migrate

What it means

The key-based ProcessInstanceMigrationBatchCmd constructor (key, version, tenantId, document) requires a non-null process definition key to resolve the migration target. A null key makes the target undefined, so Flowable throws this FlowableException immediately.

Source

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

    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;
        this.processDefinitionVersion = processDefinitionVersion;
        this.processDefinitionTenantId = processDefinitionTenantId;
        this.processInstanceMigrationDocument = processInstanceMigrationDocument;
    }

    @Override
    public Batch execute(CommandContext commandContext) {
        ProcessInstanceMigrationManager migrationManager = CommandContextUtil.getProcessEngineConfiguration(commandContext).getProcessInstanceMigrationManager();
        if (processDefinitionId != null) {
            return migrationManager.batchMigrateProcessInstancesOfProcessDefinition(processDefinitionId, processInstanceMigrationDocument, commandContext);
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Supply the correct BPMN process definition key (the id attribute of the process element, not the deployment id).
2. If you have a definition id instead of a key, use the id-based constructor.
3. Null-check the key before constructing the command.

Example fix

// before
new ProcessInstanceMigrationBatchCmd(null, 2, "tenant-1", doc);
// after
String key = "orderProcess"; // BPMN <process id="orderProcess">
new ProcessInstanceMigrationBatchCmd(key, 2, "tenant-1", doc);

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

When it happens

Trigger: Calling new ProcessInstanceMigrationBatchCmd(null, version, tenantId, migrationDocument) — the key variable was null (unresolved config, query result, or map lookup).

Common situations: Reading the process key from properties/environment that was not set; dynamic target selection where the key lookup returned null; using the key-based constructor with an id by mistake (id present, key null).

Related errors

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