{"record":{"id":"333de6864fdb7fae","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-id-to-migrate-333de6","errorCode":null,"errorMessage":"Must specify a case definition id to migrate","messagePattern":"Must specify a case definition id to migrate","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationBatchCmd.java","lineNumber":38,"sourceCode":"import org.flowable.common.engine.api.FlowableException;\nimport org.flowable.common.engine.impl.interceptor.Command;\nimport org.flowable.common.engine.impl.interceptor.CommandContext;\n\npublic class HistoricCaseInstanceMigrationBatchCmd implements Command<Batch> {\n\n    protected CmmnEngineConfiguration cmmnEngineConfiguration;\n    \n    protected String caseDefinitionId;\n    protected String caseDefinitionKey;\n    protected int caseDefinitionVersion;\n    protected String caseDefinitionTenantId;\n    protected HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument;\n\n    public HistoricCaseInstanceMigrationBatchCmd(HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument, String caseDefinitionId,\n            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseDefinitionId == null) {\n            throw new FlowableException(\"Must specify a case definition id to migrate\");\n        }\n        if (historicCaseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a historic case instance migration document to migrate\");\n        }\n        this.caseDefinitionId = caseDefinitionId;\n        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public HistoricCaseInstanceMigrationBatchCmd(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, \n            HistoricCaseInstanceMigrationDocument historicCaseInstanceMigrationDocument, 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        }","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationBatchCmd.java#L20-L56","documentation":"HistoricCaseInstanceMigrationBatchCmd's constructor requires a target caseDefinitionId for batch-migrating historic case instances. When it is null, the command immediately throws FlowableException rather than failing later during execution. This fail-fast check guarantees the migration manager always has an unambiguous case definition to operate on.","triggerScenarios":"Calling new HistoricCaseInstanceMigrationBatchCmd(document, cmmnEngineConfiguration) variant path where caseDefinitionId is null — e.g. building the command programmatically with a variable that was never populated, or a migration builder API that left the definition id unset.","commonSituations":"Passing the result of caseDefinition.getId() from a lookup that returned null (definition not deployed under expected key/tenant); copy-pasting a single-instance migration call into the batch constructor; Spring bean wiring where the id property is missing.","solutions":["Pass a valid, deployed case definition id (from CmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(...).singleResult().getId()) into the constructor.","If you only know key/version/tenant, use the HistoricCaseInstanceMigrationBatchCmd(caseDefinitionKey, version, tenantId, document, config) constructor instead.","Null-check or assert the definition id before constructing the command so the failure surfaces in your code with a clear message."],"exampleFix":"// before\ncaseEngineConfig.getCmmnEngineConfiguration().getCommandExecutor().execute(\n    new HistoricCaseInstanceMigrationBatchCmd(doc, caseDefId, cfg)); // caseDefId == null\n\n// after\nCaseDefinition def = cmmnRepoService.createCaseDefinitionQuery()\n    .caseDefinitionKey(\"myCase\").latestVersion().singleResult();\nif (def == null) throw new IllegalStateException(\"Case definition not deployed\");\nnew HistoricCaseInstanceMigrationBatchCmd(doc, def.getId(), cfg);","handlingStrategy":"validation","validationCode":"if (caseDefinitionId == null || caseDefinitionId.isBlank())\n    throw new IllegalArgumentException(\"caseDefinitionId required for historic batch migration\");\n// optionally verify deployment:\nCaseDefinition def = cmmnRepositoryService.createCaseDefinitionQuery()\n    .caseDefinitionId(caseDefinitionId).singleResult();\nif (def == null) throw new IllegalArgumentException(\"Unknown caseDefinitionId: \" + caseDefinitionId);","typeGuard":"boolean isValidDefinitionId(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try {\n    historyService.createHistoricCaseInstanceMigrationBuilder()...executeBatch();\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Must specify a case definition id\")) {\n        throw new ConfigurationException(\"Resolve the target case definition id before migrating\", e);\n    }\n    throw e;\n}","preventionTips":["Resolve definition ids via CaseDefinitionQuery rather than hard-coded strings","Null-check constructor arguments at the call site","Prefer the builder API (HistoricCaseInstanceMigrationBuilder) over raw command construction"],"tags":["flowable","cmmn","null-argument","case-migration","constructor-validation"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}