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

Constructor guard on the case instance migration command: the caseInstanceId argument is null, so the migration document cannot be tied to a case instance and the command is rejected before execution.

Source

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

/**
 * @author Valentin Zickner
 */
public class CaseInstanceMigrationCmd implements Command<Void> {
    
    protected CmmnEngineConfiguration cmmnEngineConfiguration;

    protected String caseInstanceId;
    protected String caseDefinitionId;
    protected String caseDefinitionKey;
    protected int caseDefinitionVersion;
    protected String caseDefinitionTenantId;
    protected CaseInstanceMigrationDocument caseInstanceMigrationDocument;

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Ensure the case instance id is resolved (e.g. from CaseInstanceQuery) and non-null before constructing the command
  2. Validate at the API/controller layer that the id path/body parameter is present
  3. Check parameter order in the constructor: id first, then document

Example fix

// before
new CaseInstanceMigrationCmd(caseInstanceId, doc, config); // caseInstanceId == null
// after
if (caseInstanceId == null || caseInstanceId.isEmpty()) {
    throw new IllegalArgumentException("caseInstanceId is required");
}
new CaseInstanceMigrationCmd(caseInstanceId, doc, config);
Defensive patterns

Strategy: validation

Validate before calling

if (caseInstanceId == null || caseInstanceId.isEmpty()) {
    throw new IllegalArgumentException("caseInstanceId is required for single-instance migration");
}

Try / catch

try {
    return new CaseInstanceMigrationCmd(caseInstanceId, document, config);
} catch (FlowableException e) {
    if (e.getMessage().contains("case instance id")) {
        // resolve id from CaseInstanceQuery or reject the request upstream
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationCmd(caseInstanceId, document, config) with caseInstanceId == null, e.g. when the id came from a request parameter that was absent or a lookup that returned nothing.

Common situations: REST payload missing the caseInstanceId field; variable initialized from an empty optional; wrong variable passed due to parameter ordering (id, document, config).

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