flowable/flowable-engine · error · FlowableException

Must specify a case definition id to migrate

Error message

Must specify a case definition id to migrate

What it means

Thrown by the definition-id based CaseInstanceMigrationValidationCmd constructor when caseDefinitionId is null. To validate bulk migration for all instances of a definition, the target case definition id must be supplied.

Source

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

    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;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Fetch a real id: cmmnRepositoryService.createCaseDefinitionQuery().latestVersion().caseDefinitionKey(key).singleResult().getId() and pass it.
  2. If you only have a key/version/tenant, use the corresponding validateMigrationOfCaseDefinition(key, version, tenantId, doc) overload.
  3. Check that the definition was actually deployed and the query result is non-null before validating.

Example fix

// before
builder.validateMigrationOfCaseDefinition(caseDefinitionId, doc); // null
// after
CaseDefinition cd = cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey("orderCase").latestVersion().singleResult();
builder.validateMigrationOfCaseDefinition(cd.getId(), doc);
Defensive patterns

Strategy: validation

Validate before calling

CaseDefinition cd = key != null
    ? cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult()
    : null;
if (cd == null) {
    throw new IllegalArgumentException("case definition not deployed for key: " + key);
}

Try / catch

try {
    builder.validateMigrationOfCaseDefinition(caseDefinitionId, doc);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a case definition id")) {
        // resolve id from deployment query and retry
    }
}

Prevention

When it happens

Trigger: Calling validateMigrationOfCaseDefinition(null, document) or CaseInstanceMigrationValidationCmd(doc, null, config).

Common situations: Definition id resolved from a query that returned null; configuration key holding the deployment id never set; mixing up definition key vs definition id parameters.

Related errors

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