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

The CaseInstanceMigrationBatchCmd constructor requires a non-null CaseInstanceMigrationDocument describing the migration plan (plan items mappings, etc.). A null document gives the batch command nothing to execute, so it throws immediately.

Source

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

public class CaseInstanceMigrationBatchCmd implements Command<Batch> {

    protected CmmnEngineConfiguration cmmnEngineConfiguration;
    
    protected String caseDefinitionId;
    protected String caseDefinitionKey;
    protected int caseDefinitionVersion;
    protected String caseDefinitionTenantId;
    protected CaseInstanceMigrationDocument caseInstanceMigrationDocument;

    public CaseInstanceMigrationBatchCmd(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;
        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    public CaseInstanceMigrationBatchCmd(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, 
            CaseInstanceMigrationDocument caseInstanceMigrationDocument, CmmnEngineConfiguration cmmnEngineConfiguration) {
        
        if (caseDefinitionKey == null) {
            throw new FlowableException("Must specify a case definition id to migrate");
        }
        if (caseDefinitionTenantId == null) {
            throw new FlowableException("Must specify a case definition tenant id to migrate");
        }
        if (caseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a case instance migration document to migrate");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Build the document via CmmnEngine.getInstance().getCaseInstanceMigrationService() or CaseInstanceMigrationDocumentBuilder before constructing the command
  2. If migrating from JSON, validate CaseInstanceMigrationDocumentReader.read(json) output for null before creating the command
  3. Ensure you are passing the document to the right constructor parameter (document first, then definition id)

Example fix

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

Strategy: validation

Validate before calling

if (caseInstanceMigrationDocument == null) {
    throw new IllegalArgumentException("Migration document must be built before creating the command");
}

Try / catch

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

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config) with caseInstanceMigrationDocument == null, e.g. when the document failed to parse or was never built.

Common situations: Passing the result of CaseInstanceMigrationBuilder or a JSON parse that returned null; a variable that is conditionally initialized; refactoring left the document construction out.

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