{"record":{"id":"3e975db7cf746689","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-id-to-migrate-3e975d","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/CaseInstanceMigrationCmd.java","lineNumber":56,"sourceCode":"            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseInstanceId == null) {\n            throw new FlowableException(\"Must specify a case instance id to migrate\");\n        }\n        if (caseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a case instance migration document to migrate\");\n        }\n        \n        this.caseInstanceId = caseInstanceId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationCmd(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        \n        this.caseDefinitionId = caseDefinitionId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationCmd(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\");","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/CaseInstanceMigrationCmd.java#L38-L74","documentation":"The document+definitionId constructor of CaseInstanceMigrationCmd targets all instances of a definition... for a single migration it validates that caseDefinitionId is non-null so the target definition can be resolved; null is rejected with this message.","triggerScenarios":"Constructing new CaseInstanceMigrationCmd(document, caseDefinitionId, config) with caseDefinitionId == null, often because the definition lookup returned null or configuration lacked the target id.","commonSituations":"Target definition not deployed yet so query returned no row; environment-specific config missing the definition id; parameter order confusion (document first, then id).","solutions":["Resolve the target definition id via CmmnRepositoryService.createCaseDefinitionQuery() and pass its id","Verify the target case definition is deployed in the environment before migrating","If you only know key/version/tenant, check CaseInstanceMigrationCmd's key-based constructor if available, or resolve the id first"],"exampleFix":"// before\nnew CaseInstanceMigrationCmd(doc, caseDefinitionId, config); // caseDefinitionId == null\n// after\nCaseDefinition def = repositoryService.createCaseDefinitionQuery().caseDefinitionKey(\"myCase\").latestVersion().singleResult();\nnew CaseInstanceMigrationCmd(doc, def.getId(), config);","handlingStrategy":"validation","validationCode":"if (caseDefinitionId == null || caseDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"Target case definition id is required\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new CaseInstanceMigrationCmd(document, caseDefinitionId, config);\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Must specify a case definition\")) {\n        // resolve the definition id via CaseDefinitionQuery and retry\n    }\n    throw e;\n}","preventionTips":["Ensure the target case definition is deployed and its id resolved before migration","Query definition ids via CmmnRepositoryService instead of hardcoding config","Prefer CaseInstanceMigrationBuilder for constructing migrations safely"],"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"}