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 HistoricCaseInstanceMigrationCmd constructor requires a caseDefinitionTenantId; if it is null the constructor throws this FlowableException. Multi-tenant migrations need the tenant id to scope the case definition lookup (key+version+tenant together identify the definition), so a missing tenant makes the migration ambiguous and is rejected up front.

Source

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

            throw new FlowableException("Must specify a case definition id to migrate");
        }
        if (historicCaseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a historic case instance migration document to migrate");
        }
        
        this.caseDefinitionId = caseDefinitionId;
        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

    public HistoricCaseInstanceMigrationCmd(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, 
            HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument, 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 (historicCaseInstanceMigrationDocument == null) {
            throw new FlowableException("Must specify a historic case instance migration document to migrate");
        }
        
        this.caseDefinitionKey = caseDefinitionKey;
        this.caseDefinitionVersion = caseDefinitionVersion;
        this.caseDefinitionTenantId = caseDefinitionTenantId;
        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;
        this.cmmnEngineConfiguration = cmmnEngineConfiguration;
    }

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

        if (caseInstanceId != null) {
            migrationManager.migrateHistoricCaseInstance(caseInstanceId, historicCaseInstanceMigrationDocument, commandContext);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Provide the tenant id of the case definition as the third constructor argument
2. If the deployment has no tenants, pass an explicit empty/zero-tenant value consistent with how definitions were deployed rather than null
3. Validate tenant configuration before building the migration command

Example fix

// before
new HistoricCaseInstanceMigrationCmd("myCase", 2, null, doc, config);
// after
new HistoricCaseInstanceMigrationCmd("myCase", 2, "myTenant", doc, config);

if (tenantId == null) throw new IllegalArgumentException("caseDefinitionTenantId is required for historic case migration");

try { new HistoricCaseInstanceMigrationCmd(key, version, tenantId, doc, config); } catch (FlowableException e) { log.error("Missing tenant id for migration: {}", e.getMessage()); }

When it happens

Trigger: Constructing HistoricCaseInstanceMigrationCmd with a non-null key and version but a null caseDefinitionTenantId — typically when the tenant was omitted from a migration builder or config for a multi-tenant deployment.

Common situations: Single-tenant setups copied into multi-tenant environments where tenant ids are now mandatory; builders where setTenantId() was never called; reading tenant from a null request header/property.

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

• app definition tenantId is null
• Case instance id is null
• Plan item instance id is null
• taskId is null
• caseInstanceId is required

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/815ea161a724d17f. Report an issue: GitHub.