{"record":{"id":"bd99ade220804ece","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-id-to-migrate","errorCode":null,"errorMessage":"Must specify a case definition id to migrate","messagePattern":"Must specify a case definition 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/CaseInstanceMigrationBatchCmd.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 CaseInstanceMigrationBatchCmd 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 CaseInstanceMigrationDocument caseInstanceMigrationDocument;\n\n    public CaseInstanceMigrationBatchCmd(CaseInstanceMigrationDocument caseInstanceMigrationDocument, 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 (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 CaseInstanceMigrationBatchCmd(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        }","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/CaseInstanceMigrationBatchCmd.java#L20-L56","documentation":"CaseInstanceMigrationBatchCmd's constructor requires a target case definition id for the migration batch; if it is null the command cannot know which case definition to migrate to and throws immediately. The migration document describes how to move case instances to a specific target definition, so that id is mandatory.","triggerScenarios":"Constructing new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, cmmnEngineConfiguration) with a null caseDefinitionId, typically when the id was derived from a lookup that returned null or from unset configuration.","commonSituations":"Passing the result of an optional case-definition lookup; configuration property for the target definition missing; variable shadowing where the wrong variable is passed.","solutions":["Resolve the target case definition id before building the command, e.g. via CmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult()","Validate the id for null/empty at the caller and fail early with a clearer message","If you only have key/version/tenant, use the other constructor CaseInstanceMigrationBatchCmd(key, version, tenantId, document, config) instead"],"exampleFix":"// before\nnew CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config); // caseDefinitionId == null\n// after\nCaseDefinition def = repositoryService.createCaseDefinitionQuery().caseDefinitionKey(\"myCase\").latestVersion().singleResult();\nnew CaseInstanceMigrationBatchCmd(document, def.getId(), config);","handlingStrategy":"validation","validationCode":"if (caseDefinitionId == null || caseDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"Target case definition id is required for migration\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new CaseInstanceMigrationBatchCmd(document, caseDefinitionId, config);\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Must specify\")) {\n        // resolve the definition id from key or config and retry\n    }\n    throw e;\n}","preventionTips":["Resolve definition ids via CaseDefinitionQuery before migration","Fail fast on empty configuration values for target definitions","Prefer the builder API (CaseInstanceMigrationBuilder) which enforces target selection"],"tags":["cmmn","migration","null-argument","constructor"],"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"}