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

The document+definitionId constructor of CaseInstanceMigrationCmd targets all instances of a definition... for a single migration it validates that caseDefinitionId is non-null so the target definition can be resolved; null is rejected with this message.

Source

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

            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 CaseInstanceMigrationCmd(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 CaseInstanceMigrationCmd(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. Resolve the target definition id via CmmnRepositoryService.createCaseDefinitionQuery() and pass its id
  2. Verify the target case definition is deployed in the environment before migrating
  3. If you only know key/version/tenant, check CaseInstanceMigrationCmd's key-based constructor if available, or resolve the id first

Example fix

// before
new CaseInstanceMigrationCmd(doc, caseDefinitionId, config); // caseDefinitionId == null
// after
CaseDefinition def = repositoryService.createCaseDefinitionQuery().caseDefinitionKey("myCase").latestVersion().singleResult();
new CaseInstanceMigrationCmd(doc, def.getId(), config);
Defensive patterns

Strategy: validation

Validate before calling

if (caseDefinitionId == null || caseDefinitionId.isEmpty()) {
    throw new IllegalArgumentException("Target case definition id is required");
}

Try / catch

try {
    return new CaseInstanceMigrationCmd(document, caseDefinitionId, config);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Must specify a case definition")) {
        // resolve the definition id via CaseDefinitionQuery and retry
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationCmd(document, caseDefinitionId, config) with caseDefinitionId == null, often because the definition lookup returned null or configuration lacked the target id.

Common situations: Target definition not deployed yet so query returned no row; environment-specific config missing the definition id; parameter order confusion (document first, then id).

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