{"record":{"id":"36ccc9e9abec2542","repo":"flowable/flowable-engine","slug":"cannot-find-the-historic-case-instance-to-migrate","errorCode":null,"errorMessage":"Cannot find the historic case instance to migrate, with id${caseInstanceId}","messagePattern":"Cannot find the historic case instance to migrate, with id(.+?)","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":228,"sourceCode":"\n    @Override\n    public void migrateCaseInstance(String caseInstanceId, CaseInstanceMigrationDocument document, CommandContext commandContext) {\n        CaseInstanceEntityManager caseInstanceEntityManager = CommandContextUtil.getCaseInstanceEntityManager(commandContext);\n        CaseInstanceEntity caseInstance = caseInstanceEntityManager.findById(caseInstanceId);\n        if (caseInstance == null) {\n            throw new FlowableException(\"Cannot find the case to migrate, with id\" + caseInstanceId);\n        }\n\n        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);\n        doMigrateCaseInstance(caseInstance, caseDefinitionToMigrateTo, document, commandContext);\n    }\n    \n    @Override\n    public void migrateHistoricCaseInstance(String caseInstanceId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {\n        HistoricCaseInstanceEntityManager historicCaseInstanceEntityManager = CommandContextUtil.getHistoricCaseInstanceEntityManager(commandContext);\n        HistoricCaseInstanceEntity caseInstance = historicCaseInstanceEntityManager.findById(caseInstanceId);\n        if (caseInstance == null) {\n            throw new FlowableException(\"Cannot find the historic case instance to migrate, with id\" + caseInstanceId);\n        }\n        \n        if (!CaseInstanceState.END_STATES.contains(caseInstance.getState())) {\n            throw new FlowableException(\"Historic case instance has not ended and can only be migrated with the regular case instance migrate method (migrateCaseInstance) for id \" + caseInstanceId);\n        }\n\n        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);\n        doMigrateHistoricCaseInstance(caseInstance, caseDefinitionToMigrateTo, document, commandContext);\n    }\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) {","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationManagerImpl.java#L210-L246","documentation":"Failure in CaseInstanceMigrationManagerImpl.migrateHistoricCaseInstance: the historic case instance record for the given id cannot be found, so there is nothing to migrate (already purged by history TTL or wrong id).","triggerScenarios":"Calling migrateHistoricCaseInstance(caseInstanceId, document, commandContext) with an id that has no historic case instance row — e.g. the case is still running (not yet historic), the id is wrong, or history level did not record the instance.","commonSituations":"Passing a running case's id to the historic migration method; querying the wrong engine/database; history level configured too low so no historic record exists; typo in id.","solutions":["Verify with CmmnHistoryService.createHistoricCaseInstanceQuery().caseInstanceId(id) that the historic record exists","If the case is still running, use migrateCaseInstance instead","Check you are connected to the engine/database that owns the instance","Ensure history is enabled at a level that records case instances"],"exampleFix":"// before\nhistoryMigrationManager.migrateHistoricCaseInstance(caseId, doc, commandContext); // may not be historic\n// after\nif (historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseId).finished().count() > 0) {\n    historyMigrationManager.migrateHistoricCaseInstance(caseId, doc, commandContext);\n}","handlingStrategy":"validation","validationCode":"const hist = historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseId).singleResult();\nif (hist == null) throw new Error('No historic case instance with id ' + caseId);","typeGuard":"function isHistoricCase(q) { return q.singleResult() != null; }","tryCatchPattern":"try { migrateHistoricCaseInstance(id, doc); } catch (e) { if (String(e.message).startsWith('Cannot find the historic case instance')) { throw new NotFoundError('Historic case ' + id + ' missing (still running or history disabled?)'); } throw e; }","preventionTips":["Check history level is configured to record case instances","Use .finished() queries to confirm end-state before historic migration","Verify the id against CmmnHistoryService results"],"tags":["cmmn","migration","history","entity-not-found"],"backgroundTag":"record-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"}