{"record":{"id":"65a0044e35b6dcb8","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-id-to-migrate-65a004","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/CaseInstanceMigrationValidationCmd.java","lineNumber":56,"sourceCode":"    public CaseInstanceMigrationValidationCmd(String caseInstanceId, CaseInstanceMigrationDocument caseInstanceMigrationDocument,\n            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        this.caseInstanceId = caseInstanceId;\n        this.caseInstanceMigrationDocument = caseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public CaseInstanceMigrationValidationCmd(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 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        }","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/CaseInstanceMigrationValidationCmd.java#L38-L74","documentation":"Thrown by the definition-id based CaseInstanceMigrationValidationCmd constructor when caseDefinitionId is null. To validate bulk migration for all instances of a definition, the target case definition id must be supplied.","triggerScenarios":"Calling validateMigrationOfCaseDefinition(null, document) or CaseInstanceMigrationValidationCmd(doc, null, config).","commonSituations":"Definition id resolved from a query that returned null; configuration key holding the deployment id never set; mixing up definition key vs definition id parameters.","solutions":["Fetch a real id: cmmnRepositoryService.createCaseDefinitionQuery().latestVersion().caseDefinitionKey(key).singleResult().getId() and pass it.","If you only have a key/version/tenant, use the corresponding validateMigrationOfCaseDefinition(key, version, tenantId, doc) overload.","Check that the definition was actually deployed and the query result is non-null before validating."],"exampleFix":"// before\nbuilder.validateMigrationOfCaseDefinition(caseDefinitionId, doc); // null\n// after\nCaseDefinition cd = cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(\"orderCase\").latestVersion().singleResult();\nbuilder.validateMigrationOfCaseDefinition(cd.getId(), doc);","handlingStrategy":"validation","validationCode":"CaseDefinition cd = key != null\n    ? cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult()\n    : null;\nif (cd == null) {\n    throw new IllegalArgumentException(\"case definition not deployed for key: \" + key);\n}","typeGuard":null,"tryCatchPattern":"try {\n    builder.validateMigrationOfCaseDefinition(caseDefinitionId, doc);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Must specify a case definition id\")) {\n        // resolve id from deployment query and retry\n    }\n}","preventionTips":["Resolve definition ids through the repository service, never assume a pre-set variable.","Distinguish key vs id clearly in your service layer naming.","Verify deployment before scheduling bulk migrations."],"tags":["cmmn","case-migration","validation","null-argument"],"backgroundTag":"null-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"}