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

Thrown by the single-instance CaseInstanceMigrationValidationCmd constructor when the CaseInstanceMigrationDocument is null. Validation needs the document to know the target definition and mappings to check against the instance's current state.

Source

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

public class CaseInstanceMigrationValidationCmd implements Command<CaseInstanceMigrationValidationResult> {

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

    public CaseInstanceMigrationValidationCmd(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 CaseInstanceMigrationValidationCmd(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;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Build the migration document before validation and pass the non-null reference.
  2. Ensure the fluent builder chain ends with .build() to produce the document.
  3. Guard asynchronous flows so validation only runs after the document is created.

Example fix

// before
builder.migrateToCaseDefinition("orderCase", 2, "t1");
builder.validateMigration(instanceId, null);
// after
CaseInstanceMigrationDocument doc = builder.migrateToCaseDefinition("orderCase", 2, "t1").build();
builder.validateMigration(instanceId, doc);
Defensive patterns

Strategy: validation

Validate before calling

if (migrationDocument == null) {
    throw new IllegalArgumentException("migration document required for validation");
}

Try / catch

try {
    builder.validateMigration(caseInstanceId, doc);
} catch (FlowableException e) {
    if (e.getMessage().contains("case instance migration document")) {
        // build the document and re-run validation
    }
}

Prevention

When it happens

Trigger: Calling validateMigration(caseInstanceId, null) or CaseInstanceMigrationValidationCmd(id, null, config).

Common situations: Builder API used without a migrateToCaseDefinition step; document loaded asynchronously and not yet available when validation is invoked.

Related errors

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