flowable/flowable-engine · error · FlowableException

Cannot find the case definition to migrate to, identified by

Error message

Cannot find the case definition to migrate to, identified by ${printCaseDefinitionIdentifierMessage(document)}

What it means

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.

Source

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

    }

    @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) {
        CaseDefinition caseDefinition = resolveCaseDefinition(caseDefinitionKey, caseDefinitionVersion, caseDefinitionTenantId, commandContext);
        migrateHistoricCaseInstancesOfCaseDefinition(caseDefinition.getId(), document, commandContext);
    }

    @Override
    public void migrateCaseInstancesOfCaseDefinition(String caseDefinitionId, CaseInstanceMigrationDocument document, CommandContext commandContext) {
        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);
        if (caseDefinitionToMigrateTo == null) {
            throw new FlowableException("Cannot find the case definition to migrate to, identified by " + printCaseDefinitionIdentifierMessage(document));
        }

        CaseInstanceQueryImpl caseInstanceQueryByCaseDefinitionId = new CaseInstanceQueryImpl(commandContext, cmmnEngineConfiguration).caseDefinitionId(caseDefinitionId);
        Set<String> caseInstanceIdsToMigrate = document.getCaseInstanceIdsToMigrate();
        if (caseInstanceIdsToMigrate != null && !caseInstanceIdsToMigrate.isEmpty()) {
            caseInstanceQueryByCaseDefinitionId.caseInstanceIds(caseInstanceIdsToMigrate);
        }
        CaseInstanceEntityManager caseInstanceEntityManager = cmmnEngineConfiguration.getCaseInstanceEntityManager();
        List<CaseInstance> caseInstances = caseInstanceEntityManager.findByCriteria(caseInstanceQueryByCaseDefinitionId);

        for (CaseInstance caseInstance : caseInstances) {
            doMigrateCaseInstance((CaseInstanceEntity) caseInstance, caseDefinitionToMigrateTo, document, commandContext);
        }
    }
    
    @Override
    public void migrateHistoricCaseInstancesOfCaseDefinition(String caseDefinitionId, HistoricCaseInstanceMigrationDocument document, CommandContext commandContext) {
        CaseDefinition caseDefinitionToMigrateTo = resolveCaseDefinition(document, commandContext);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the target definition exists: repositoryService/cmmnRepositoryService.createCaseDefinitionQuery().caseDefinitionKey(key).list()
2. Include the correct tenantId in the migration document, or omit it if using a single tenant
3. Deploy the target case definition model before running migration
4. Check key spelling and version number in the document's migrateToCaseDefinition block

Example fix

// before
builder.migrateToCaseDefinition("myCasDef", 3) // version 3 never deployed
       .migrateCaseInstancesOfCaseDefinition("oldDefId");
// after
CaseDefinition def = repositoryService.createCaseDefinitionQuery()
    .caseDefinitionKey("myCaseDef").caseDefinitionVersion(2).latestVersion().singleResult();
builder.migrateToCaseDefinition(def.getKey(), def.getVersion())
       .migrateCaseInstancesOfCaseDefinition("oldDefId");

const def = repositoryService.createCaseDefinitionQuery()
  .caseDefinitionKey(doc.migrateToCaseDefinition.key)
  .caseDefinitionVersion(doc.migrateToCaseDefinition.version)
  .singleResult();
if (def == null) throw new Error('Target case definition not deployed: ' + doc.migrateToCaseDefinition.key);

function targetDefinitionExists(doc, query) { return query.caseDefinitionKey(doc.migrateToCaseDefinition.key).singleResult() != null; }

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

When it happens

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

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

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Cannot find case definition with id
• Cannot find case definition for id:
• No case definition found for id = '
• No case definition found for key <caseDefinitionKey>
• Case definition was not found by key '<caseDefinitionKey>'.

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