{"record":{"id":"31ab7e0ef7648801","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-tenant-id-to-migrat-31ab7e","errorCode":null,"errorMessage":"Must specify a case definition tenant id to migrate","messagePattern":"Must specify a case definition tenant id to migrate","errorType":"validation","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationValidationCmd.java","lineNumber":73,"sourceCode":"        if (caseDefinitionId == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }\n        this.caseDefinitionId = caseDefinitionId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationValidationCmd(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, \n            CaseInstanceMigrationDocument caseInstanceMigrationDocument, CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseDefinitionKey == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (caseDefinitionTenantId == null) {\n            throw new FlowableException(\"Must specify a case definition tenant id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }\n        this.caseDefinitionKey = caseDefinitionKey;\n        this.caseDefinitionVersion = caseDefinitionVersion;\n        this.caseDefinitionTenantId = caseDefinitionTenantId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    @Override\n    public CaseInstanceMigrationValidationResult execute(CommandContext commandContext) {\n        CaseInstanceMigrationManager migrationManager = cmmnEngineConfiguration.getCaseInstanceMigrationManager();\n\n        if (caseInstanceId != null) {\n            return migrationManager.validateMigrateCaseInstance(caseInstanceId, caseInstanceMigrationDocument, commandContext);\n        } else if (caseDefinitionId != null) {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationValidationCmd.java#L55-L91","documentation":"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.","triggerScenarios":"Calling caseInstanceMigrationBuilder.migrateCaseInstances() with migrateToCaseDefinitionKeyAndVersion(...) (or key/version without a tenant) so that caseDefinitionTenantId is null when CaseInstanceMigrationValidationCmd is constructed.","commonSituations":"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.","solutions":["Call migrateToCaseDefinitionTenantId(\"<tenantId>\") on the CaseInstanceMigrationBuilder before executing the migration.","Alternatively switch to id-based migration via migrateToCaseDefinition(caseDefinitionId), which does not need a tenant id.","Pass \"\" (empty string) only if the case was deployed under the default/no tenant and the API accepts it — prefer an explicit tenant id."],"exampleFix":"// before\nmigrationBuilder.migrateCaseInstances()\n    .migrateToCaseDefinitionKeyAndVersion(\"expenseCase\", 2);\n\n// after\nmigrationBuilder.migrateCaseInstances()\n    .migrateToCaseDefinitionKeyAndVersion(\"expenseCase\", 2)\n    .migrateToCaseDefinitionTenantId(\"acme\");","handlingStrategy":"validation","validationCode":"if (tenantId == null || tenantId.isBlank()) throw new IllegalArgumentException(\"tenantId required for key-based case migration\");","typeGuard":null,"tryCatchPattern":"try { migrationBuilder.migrateCaseInstances(); } catch (FlowableException e) { logger.error(\"case migration failed: \" + e.getMessage(), e); }","preventionTips":["Always pair migrateToCaseDefinitionKeyAndVersion with migrateToCaseDefinitionTenantId.","Centralize migration building in a helper that asserts all required fields.","Prefer definition-id based migration in single-tenant setups to avoid tenant handling."],"tags":["cmmn","case-migration","tenant","validation","java"],"backgroundTag":"missing-required-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}