{"record":{"id":"421e97a85ee7d67e","repo":"flowable/flowable-engine","slug":"must-specify-a-case-definition-id-to-migrate-421e97","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/HistoricCaseInstanceMigrationCmd.java","lineNumber":53,"sourceCode":"            CmmnEngineConfiguration cmmnEngineConfiguration) {\n        \n        if (caseInstanceId == null) {\n            throw new FlowableException(\"Must specify a historic case instance id to migrate\");\n        }\n        if (historicCaseInstanceMigrationDocument == null) {\n            throw new FlowableException(\"Must specify a historic case instance migration document to migrate\");\n        }\n        \n        this.caseInstanceId = caseInstanceId;\n        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public HistoricCaseInstanceMigrationCmd(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        \n        this.caseDefinitionId = caseDefinitionId;\n        this.historicCaseInstanceMigrationDocument = historicCaseInstanceMigrationDocument;\n        this.cmmnEngineConfiguration = cmmnEngineConfiguration;\n    }\n\n    public HistoricCaseInstanceMigrationCmd(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\");","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/cmd/HistoricCaseInstanceMigrationCmd.java#L35-L71","documentation":"This constructor of HistoricCaseInstanceMigrationCmd migrates ALL historic case instances of a given case definition by id. It validates that caseDefinitionId is non-null, throwing FlowableException immediately otherwise, since a batch-by-definition migration without the target definition id cannot proceed.","triggerScenarios":"Calling new HistoricCaseInstanceMigrationCmd(migrationDocument, null, cmmnEngineConfiguration) — e.g. definition id from an unpopulated lookup, wrong constructor overload chosen (id passed into the single-instance position or vice versa), or a null from a properties/CDI/Spring injection point.","commonSituations":"Definition deployed under a different key so createCaseDefinitionQuery() returned null and getId() was never called; copy-paste refactor dropped the id argument; confusing id vs key (this overload needs the database id, not the model key).","solutions":["Resolve the definition id first: cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).latestVersion().singleResult().getId().","If you only have the key, use a key/version/tenant-based migration builder variant instead of this id-based command.","Null-check the id before constructing the command."],"exampleFix":"// before\nString defId = caseDefinitionQuery.singleResult() != null\n    ? caseDefinitionQuery.singleResult().getId() : null; // null when not found\nnew HistoricCaseInstanceMigrationCmd(doc, defId, cfg);\n\n// after\nCaseDefinition def = caseDefinitionQuery.singleResult();\nif (def == null) throw new IllegalStateException(\"Deploy the case definition first\");\nnew HistoricCaseInstanceMigrationCmd(doc, def.getId(), cfg);","handlingStrategy":"validation","validationCode":"if (caseDefinitionId == null || caseDefinitionId.isBlank())\n    throw new IllegalArgumentException(\"caseDefinitionId required to migrate historic instances of a definition\");\nCaseDefinition def = cmmnRepositoryService.createCaseDefinitionQuery()\n    .caseDefinitionId(caseDefinitionId).singleResult();\nif (def == null) throw new IllegalArgumentException(\"No deployed case definition with id \" + caseDefinitionId);","typeGuard":"boolean isValidDefinitionId(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try {\n    execute(new HistoricCaseInstanceMigrationCmd(doc, caseDefinitionId, cfg));\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Must specify a case definition id\")) {\n        throw new ConfigurationException(\"Resolve the deployed definition id first\", e);\n    }\n    throw e;\n}","preventionTips":["Resolve ids from CaseDefinitionQuery, never from user input or config alone","Check that the definition is deployed in the target engine before migrating","Don't confuse the by-instance-id and by-definition-id constructor overloads"],"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"}