flowable/flowable-engine · error · FlowableException

Must specify a case instance migration document to migrate

Error message

Must specify a case instance migration document to migrate

What it means

CaseInstanceMigrationCmd requires a non-null CaseInstanceMigrationDocument containing the migration plan; a null document is rejected in the constructor since there is nothing to execute for the instance.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationCmd.java:44

public class CaseInstanceMigrationCmd implements Command<Void> {
    
    protected CmmnEngineConfiguration cmmnEngineConfiguration;

    protected String caseInstanceId;
    protected String caseDefinitionId;
    protected String caseDefinitionKey;
    protected int caseDefinitionVersion;
    protected String caseDefinitionTenantId;
    protected CaseInstanceMigrationDocument caseInstanceMigrationDocument;

    public CaseInstanceMigrationCmd(String caseInstanceId, CaseInstanceMigrationDocument caseInstanceMigrationDocument,
            CmmnEngineConfiguration cmmnEngineConfiguration) {
        
        if (caseInstanceId == null) {
            throw new FlowableException("Must specify a case instance id to migrate");
        }
        if (caseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a case instance migration document to migrate");
        }
        
        this.caseInstanceId = caseInstanceId;
        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    public CaseInstanceMigrationCmd(CaseInstanceMigrationDocument caseInstanceMigrationDocument, String caseDefinitionId,
            CmmnEngineConfiguration cmmnEngineConfiguration) {
        
        if (caseDefinitionId == null) {
            throw new FlowableException("Must specify a case definition id to migrate");
        }
        if (caseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a case instance migration document to migrate");
        }
        
        this.caseDefinitionId = caseDefinitionId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Build the document with CaseInstanceMigrationDocumentBuilder...build() before constructing the command
  2. When reading from JSON, use CaseInstanceMigrationDocumentReader and validate the output is non-null
  3. Confirm the constructor argument order: (caseInstanceId, document, configuration)

Example fix

// before
new CaseInstanceMigrationCmd(id, null, config); // throws
// after
CaseInstanceMigrationDocument doc = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(targetId).build();
new CaseInstanceMigrationCmd(id, doc, config);
Defensive patterns

Strategy: validation

Validate before calling

if (caseInstanceMigrationDocument == null) {
    throw new IllegalArgumentException("Migration document must be provided");
}

Try / catch

try {
    return new CaseInstanceMigrationCmd(caseInstanceId, document, config);
} catch (FlowableException e) {
    if (e.getMessage().contains("migration document")) {
        document = CaseInstanceMigrationDocumentBuilder.create().withTargetCaseDefinitionId(targetId).build();
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationCmd(caseInstanceId, document, config) with caseInstanceMigrationDocument == null, typically because document building or JSON parsing failed upstream.

Common situations: Builder chain short-circuited; passing the result of a reader method that can return null; argument order confusion between id and document.

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/ed4df87c51cc49ce. Report an issue: GitHub.