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

The ProcessInstanceMigrationValidationCmd constructor variant that validates all process instances of a process definition requires the processDefinitionId argument. A null id means the engine cannot resolve the definition whose instances should be validated, so it throws this FlowableException before doing any work.

Solutions

1. Resolve a real definition id first: repositoryService.createProcessDefinitionQuery().processDefinitionKey(key).latestVersion().singleId() and null-check the result
2. If you only have a key, use the key+version constructor variant instead
3. Validate the id string is non-null and non-empty before constructing the command

Example fix

// before
new ProcessInstanceMigrationValidationCmd(doc, defId); // defId null
// after
ProcessDefinition def = repositoryService.createProcessDefinitionQuery()
    .processDefinitionKey("order").latestVersion().singleResult();
if (def != null) {
    new ProcessInstanceMigrationValidationCmd(doc, def.getId());
}

if (processDefinitionId == null || processDefinitionId.isEmpty()) {
    throw new IllegalArgumentException("processDefinitionId is required");
}

boolean hasDefinitionId(String id) { return id != null && !id.isEmpty(); }

try {
    new ProcessInstanceMigrationValidationCmd(doc, defId).execute(commandContext);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a process definition id")) {
        // re-resolve definition id from repositoryService and retry
    }
    throw e;
}

When it happens

Trigger: Calling new ProcessInstanceMigrationValidationCmd(document, null) (document-first constructor) with a null processDefinitionId, or a null id propagated from a repository lookup.

Common situations: Definition id fetched via repositoryService.createProcessDefinitionQuery() that returned no match; key/id confusion (passing a key where an id is expected then null after lookup); direct use of internal command classes in tooling.

Related errors

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

Appendix: source

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

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

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

View on GitHub (pinned to d6d39ce1c6)