flowable/flowable-engine · error · FlowableException

Must specify a case definition tenant id to migrate

Error message

Must specify a case definition tenant id to migrate

What it means

Thrown by the key/version/tenant-based CaseInstanceMigrationCmd constructor when caseDefinitionTenantId is null. When targeting a case definition by key+version, the tenant id is required to resolve the deployed definition in a multi-tenant setup.

Source

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

            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");
        }
        if (caseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a case instance migration document to migrate");
        }
        
        this.caseDefinitionKey = caseDefinitionKey;
        this.caseDefinitionVersion = caseDefinitionVersion;
        this.caseDefinitionTenantId = caseDefinitionTenantId;
        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    @Override
    public Void execute(CommandContext commandContext) {
        CaseInstanceMigrationManager migrationManager = cmmnEngineConfiguration.getCaseInstanceMigrationManager();

        if (caseInstanceId != null) {
            migrationManager.migrateCaseInstance(caseInstanceId, caseInstanceMigrationDocument, commandContext);

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass the correct tenant id: migrateToCaseDefinition(key, version, tenantId).
  2. If no tenant isolation is used, target the definition by id instead (migrateToCaseDefinition(caseDefinitionId)).
  3. Verify the tenant id is obtained from the authenticated tenant context before building the migration.

Example fix

// before
builder.migrateToCaseDefinition("orderCase", 2, null);
// after
builder.migrateToCaseDefinition("orderCase", 2, tenantService.getCurrentTenantId());
Defensive patterns

Strategy: validation

Validate before calling

if (tenantId == null || tenantId.isEmpty()) {
    throw new IllegalArgumentException("tenant id required when targeting by key+version");
}

Try / catch

try {
    builder.migrateToCaseDefinition(key, version, tenantId);
} catch (FlowableException e) {
    if (e.getMessage().contains("Must specify a case definition tenant id")) {
        // fall back to tenant-less id-based targeting
    }
}

Prevention

When it happens

Trigger: Calling createCaseInstanceMigrationBuilder().migrateToCaseDefinition(caseDefinitionKey, version, null).

Common situations: Multi-tenant deployments where tenant resolution fails or the tenant context is not propagated; single-tenant apps incorrectly forced into the key/version/tenant variant instead of using migrateToCaseDefinition(id) or key+version without tenant.

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