{"record":{"id":"69450cd727755846","repo":"flowable/flowable-engine","slug":"cannot-find-the-case-definition-to-migrate-to-ide","errorCode":null,"errorMessage":"Cannot find the case definition to migrate to, identified by ${printCaseDefinitionIdentifierMessage(document)}","messagePattern":"Cannot find the case definition to migrate to, identified by (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationManagerImpl.java","lineNumber":255,"sourceCode":"    }\n\n    @Override\n    public void migrateCaseInstancesOfCaseDefinition(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, CaseInstanceMigrationDocument document, CommandContext commandContext) {\n        CaseDefinition caseDefinition = resolveCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, commandContext);\n        migrateCaseInstancesOfCaseDefinition(caseDefinition.getId(), document, commandContext);\n    }\n    \n    @Override\n    public void migrateHistoricCaseInstancesOfCaseDefinition(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {\n        CaseDefinition caseDefinition = resolveCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, commandContext);\n        migrateHistoricCaseInstancesOfCaseDefinition(caseDefinition.getId(), document, commandContext);\n    }\n\n    @Override\n    public void migrateCaseInstancesOfCaseDefinition(String caseDefinitionId, CaseInstanceMigrationDocument document, CommandContext commandContext) {\n        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);\n        if (caseDefinitionToMigrateTo == null) {\n            throw new FlowableException(\"Cannot find the case definition to migrate to, identified by \" + printCaseDefinitionIdentifierMessage(document));\n        }\n\n        CaseInstanceQueryImpl caseInstanceQueryByCaseDefinitionId = new CaseInstanceQueryImpl(commandContext, cmmnEngineConfiguration).caseDefinitionId(caseDefinitionId);\n        Set<String> caseInstanceIdsToMigrate = document.getCaseInstanceIdsToMigrate();\n        if (caseInstanceIdsToMigrate != null && !caseInstanceIdsToMigrate.isEmpty()) {\n            caseInstanceQueryByCaseDefinitionId.caseInstanceIds(caseInstanceIdsToMigrate);\n        }\n        CaseInstanceEntityManager caseInstanceEntityManager = cmmnEngineConfiguration.getCaseInstanceEntityManager();\n        List<CaseInstance> caseInstances = caseInstanceEntityManager.findByCriteria(caseInstanceQueryByCaseDefinitionId);\n\n        for (CaseInstance caseInstance : caseInstances) {\n            doMigrateCaseInstance((CaseInstanceEntity) caseInstance, caseDefinitionToMigrateTo, document, commandContext);\n        }\n    }\n    \n    @Override\n    public void migrateHistoricCaseInstancesOfCaseDefinition(String caseDefinitionId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {\n        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationManagerImpl.java#L237-L273","documentation":"migrateCaseInstancesOfCaseDefinition resolves the target case definition from the migration document. If resolveCaseDefinition returns null (no definition matches the key/version/tenant in the document), this FlowableException is thrown, identifying the document's target via printCaseDefinitionIdentifierMessage.","triggerScenarios":"Calling migrateCaseInstancesOfCaseDefinition with a migration document whose target case definition does not exist: wrong key, version not deployed, tenant mismatch, or definition not yet deployed.","commonSituations":"Target model never deployed to this engine; migrating to a specific version that wasn't deployed; multi-tenant setup where the definition is deployed under a different tenant; typo in definition key.","solutions":["Verify the target definition exists: repositoryService/cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).list()","Include the correct tenantId in the migration document, or omit it if using a single tenant","Deploy the target case definition model before running migration","Check key spelling and version number in the document's migrateToCaseDefinition block"],"exampleFix":"// before\nbuilder.migrateToCaseDefinition(\"myCasDef\", 3) // version 3 never deployed\n       .migrateCaseInstancesOfCaseDefinition(\"oldDefId\");\n// after\nCaseDefinition def = repositoryService.createCaseDefinitionQuery()\n    .caseDefinitionKey(\"myCaseDef\").caseDefinitionVersion(2).latestVersion().singleResult();\nbuilder.migrateToCaseDefinition(def.getKey(), def.getVersion())\n       .migrateCaseInstancesOfCaseDefinition(\"oldDefId\");","handlingStrategy":"validation","validationCode":"const def = repositoryService.createCaseDefinitionQuery()\n  .caseDefinitionKey(doc.migrateToCaseDefinition.key)\n  .caseDefinitionVersion(doc.migrateToCaseDefinition.version)\n  .singleResult();\nif (def == null) throw new Error('Target case definition not deployed: ' + doc.migrateToCaseDefinition.key);","typeGuard":"function targetDefinitionExists(doc, query) { return query.caseDefinitionKey(doc.migrateToCaseDefinition.key).singleResult() != null; }","tryCatchPattern":"try { migrateCaseInstancesOfCaseDefinition(defId, doc); } catch (e) { if (String(e.message).startsWith('Cannot find the case definition to migrate to')) { deployTargetModel(doc.migrateToCaseDefinition); return retry(); } throw e; }","preventionTips":["Deploy the target model in the same release script that runs migration","Verify key/version/tenant with a CaseDefinitionQuery before migrating","Keep migration documents generated from deployed-definition metadata"],"tags":["cmmn","migration","case-definition","not-found"],"backgroundTag":"resource-not-found","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"}