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

Constructor guard in CaseInstanceMigrationBatchCmd: when migrating by case definition key plus version, a tenant id must also be given; it is null, so the target definition cannot be identified unambiguously.

Source

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

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

        if (caseDefinitionId != null) {
            return migrationManager.batchMigrateCaseInstancesOfCaseDefinition(caseDefinitionId, caseInstanceMigrationDocument, commandContext);
        } else if (caseDefinitionKey != null && caseDefinitionVersion >= 0) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Pass the explicit tenant id of the target definition (e.g. "" for the default tenant or the configured tenant value)
  2. Check your tenant provider/context resolution; ensure the id exists before building the command
  3. If you have the definition id, use the id-based constructor which avoids key/version/tenant resolution

Example fix

// before
new CaseInstanceMigrationBatchCmd("myCase", 2, tenantId, doc, config); // tenantId == null
// after
new CaseInstanceMigrationBatchCmd("myCase", 2, "myTenant", doc, config);
Defensive patterns

Strategy: validation

Validate before calling

if (caseDefinitionTenantId == null) {
    throw new IllegalArgumentException("Tenant id is required for key/version-based migration");
}

Try / catch

try {
    return new CaseInstanceMigrationBatchCmd(key, version, tenantId, document, config);
} catch (FlowableException e) {
    if (e.getMessage().contains("tenant id")) {
        // supply default tenant or configured tenant and retry
    }
    throw e;
}

Prevention

When it happens

Trigger: Constructing new CaseInstanceMigrationBatchCmd(key, version, tenantId, document, config) with caseDefinitionTenantId == null. Note that a negative/unset version also blocks reaching this branch since the key check runs first.

Common situations: Single-tenant deployments where developers assume tenant is unnecessary and pass null; tenant id not propagated from the request context; default tenant stored as null in 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/4eeac201b00da6bd. Report an issue: GitHub.