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

The CaseInstanceMigrationValidationCmd constructor requires both a case definition key and a tenant id when key-based (rather than id-based) migration is used. Flowable throws this FlowableException during command construction if the tenant id is null. Key+version lookups are tenant-scoped, so a tenant id must always accompany them.

Source

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

        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");
        }
        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 CaseInstanceMigrationValidationResult execute(CommandContext commandContext) {
        CaseInstanceMigrationManager migrationManager = cmmnEngineConfiguration.getCaseInstanceMigrationManager();

        if (caseInstanceId != null) {
            return migrationManager.validateMigrateCaseInstance(caseInstanceId, caseInstanceMigrationDocument, commandContext);
        } else if (caseDefinitionId != null) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Call migrateToCaseDefinitionTenantId("<tenantId>") on the CaseInstanceMigrationBuilder before executing the migration.
  2. Alternatively switch to id-based migration via migrateToCaseDefinition(caseDefinitionId), which does not need a tenant id.
  3. Pass "" (empty string) only if the case was deployed under the default/no tenant and the API accepts it — prefer an explicit tenant id.

Example fix

// before
migrationBuilder.migrateCaseInstances()
    .migrateToCaseDefinitionKeyAndVersion("expenseCase", 2);

// after
migrationBuilder.migrateCaseInstances()
    .migrateToCaseDefinitionKeyAndVersion("expenseCase", 2)
    .migrateToCaseDefinitionTenantId("acme");
Defensive patterns

Strategy: validation

Validate before calling

if (tenantId == null || tenantId.isBlank()) throw new IllegalArgumentException("tenantId required for key-based case migration");

Try / catch

try { migrationBuilder.migrateCaseInstances(); } catch (FlowableException e) { logger.error("case migration failed: " + e.getMessage(), e); }

Prevention

When it happens

Trigger: Calling caseInstanceMigrationBuilder.migrateCaseInstances() with migrateToCaseDefinitionKeyAndVersion(...) (or key/version without a tenant) so that caseDefinitionTenantId is null when CaseInstanceMigrationValidationCmd is constructed.

Common situations: Multi-tenant deployments where the tenant id was omitted from the migration builder; code copied from single-tenant examples that never called migrateToCaseDefinitionTenantId; refactors that replaced case-definition-id based migration with key/version based migration.

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