flowable/flowable-engine · error · FlowableException

Cannot find the historic case instance to migrate, with id

Error message

Cannot find the historic case instance to migrate, with id${caseInstanceId}

What it means

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).

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

Example fix

// before
historyMigrationManager.migrateHistoricCaseInstance(caseId, doc, commandContext); // may not be historic
// after
if (historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseId).finished().count() > 0) {
    historyMigrationManager.migrateHistoricCaseInstance(caseId, doc, commandContext);
}

Defensive patterns

Strategy: validation

Validate before calling

const hist = historyService.createHistoricCaseInstanceQuery().caseInstanceId(caseId).singleResult();
if (hist == null) throw new Error('No historic case instance with id ' + caseId);

Type guard

function isHistoricCase(q) { return q.singleResult() != null; }

Try / catch

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; }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/36ccc9e9abec2542. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/migration/CaseInstanceMigrationManagerImpl.java:228

    @Override
    public void migrateCaseInstance(String caseInstanceId, CaseInstanceMigrationDocument document, CommandContext commandContext) {
        CaseInstanceEntityManager caseInstanceEntityManager = CommandContextUtil.getCaseInstanceEntityManager(commandContext);
        CaseInstanceEntity caseInstance = caseInstanceEntityManager.findById(caseInstanceId);
        if (caseInstance == null) {
            throw new FlowableException("Cannot find the case to migrate, with id" + caseInstanceId);
        }

        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);
        doMigrateCaseInstance(caseInstance, caseDefinitionToMigrateTo, document, commandContext);
    }
    
    @Override
    public void migrateHistoricCaseInstance(String caseInstanceId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {
        HistoricCaseInstanceEntityManager historicCaseInstanceEntityManager = CommandContextUtil.getHistoricCaseInstanceEntityManager(commandContext);
        HistoricCaseInstanceEntity caseInstance = historicCaseInstanceEntityManager.findById(caseInstanceId);
        if (caseInstance == null) {
            throw new FlowableException("Cannot find the historic case instance to migrate, with id" + caseInstanceId);
        }
        
        if (!CaseInstanceState.END_STATES.contains(caseInstance.getState())) {
            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);
        }

        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);
        doMigrateHistoricCaseInstance(caseInstance, caseDefinitionToMigrateTo, document, commandContext);
    }

    @Override
    public void migrateCaseInstancesOfCaseDefinition(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, CaseInstanceMigrationDocument document, CommandContext commandContext) {
        CaseDefinition caseDefinition = resolveCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, commandContext);
        migrateCaseInstancesOfCaseDefinition(caseDefinition.getId(), document, commandContext);
    }
    
    @Override
    public void migrateHistoricCaseInstancesOfCaseDefinition(String caseDefinitionKey, int caseDefinitionVersion, String caseDefinitionTenantId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {

View on GitHub (pinned to d6d39ce1c6)