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.

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.

Appendix: 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)