flowable/flowable-engine · error · FlowableException

Must specify a case instance id to migrate

Error message

Must specify a case instance id to migrate

What it means

Thrown by the CaseInstanceMigrationValidationCmd constructor when caseInstanceId is null. This command validates (without executing) whether a specific case instance can be migrated per the given document, so the instance id is mandatory.

Source

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

/**
 * @author Valentin Zickner
 */
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");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass the actual case instance id: validateMigration(caseInstanceId, migrationDocument).
  2. Verify the instance exists via CmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(id).singleResult() before validating.
  3. Null-check the id variable at the caller; an earlier lookup returning null usually means the instance does not exist.

Example fix

// before
builder.validateMigration(caseInstanceId, doc); // caseInstanceId == null
// after
if (caseInstanceId != null) {
    builder.validateMigration(caseInstanceId, doc);
}
Defensive patterns

Strategy: validation

Validate before calling

if (caseInstanceId == null) {
    throw new IllegalArgumentException("case instance id required for migration validation");
}
if (cmmnRuntimeService.createCaseInstanceQuery().caseInstanceId(caseInstanceId).count() == 0) {
    throw new IllegalArgumentException("case instance does not exist: " + caseInstanceId);
}

Try / catch

try {
    builder.validateMigration(caseInstanceId, doc);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a case instance id")) {
        // instance id missing; surface a 4xx-style error to the caller
    }
}

Prevention

When it happens

Trigger: Calling createCaseInstanceMigrationBuilder().validateMigration(null, document) or constructing CaseInstanceMigrationValidationCmd(null, doc, config) directly.

Common situations: A case instance id variable read from user input or a request payload that was missing; passing the wrong variable (null after a lookup that found nothing).

Related errors

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