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

CaseInstanceMigrationBatchCmd's constructor requires a target case definition id for the migration batch; if it is null the command cannot know which case definition to migrate to and throws immediately. The migration document describes how to move case instances to a specific target definition, so that id is mandatory.

Source

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

import org.flowable.common.engine.api.FlowableException;
import org.flowable.common.engine.impl.interceptor.Command;
import org.flowable.common.engine.impl.interceptor.CommandContext;

public class CaseInstanceMigrationBatchCmd implements Command<Batch> {

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

    public CaseInstanceMigrationBatchCmd(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 CaseInstanceMigrationBatchCmd(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 case definition id before building the command, e.g. via CmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult()
  2. Validate the id for null/empty at the caller and fail early with a clearer message
  3. If you only have key/version/tenant, use the other constructor CaseInstanceMigrationBatchCmd(key, version, tenantId, document, config) instead

Example fix

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

Strategy: validation

Validate before calling

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

Try / catch

try {
    return new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Must specify")) {
        // resolve the definition id from key or config and retry
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, cmmnEngineConfiguration) with a null caseDefinitionId, typically when the id was derived from a lookup that returned null or from unset configuration.

Common situations: Passing the result of an optional case-definition lookup; configuration property for the target definition missing; variable shadowing where the wrong variable is passed.

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