{"record":{"id":"8b38e90e14488de7","repo":"flowable/flowable-engine","slug":"cannot-find-the-process-definition-to-migrate-to","errorCode":null,"errorMessage":"Cannot find the process definition to migrate to, identified by \" + printProcessDefinitionIdentifierMessage(document)","messagePattern":"Cannot find the process definition to migrate to, identified by \" \\+ printProcessDefinitionIdentifierMessage\\(document\\)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java","lineNumber":399,"sourceCode":"            timerJob.setRepeat(processEngineConfiguration.getBatchStatusTimeCycleConfig());\n            \n            timerJobService.scheduleTimerJob(timerJob);\n        }\n\n        return batch;\n    }\n\n    @Override\n    public void migrateProcessInstancesOfProcessDefinition(String procDefKey, int procDefVer, String procDefTenantId, ProcessInstanceMigrationDocument document, CommandContext commandContext) {\n        ProcessDefinition processDefinition = resolveProcessDefinition(procDefKey, procDefVer, procDefTenantId, commandContext);\n        migrateProcessInstancesOfProcessDefinition(processDefinition.getId(), document, commandContext);\n    }\n\n    @Override\n    public void migrateProcessInstancesOfProcessDefinition(String processDefinitionId, ProcessInstanceMigrationDocument document, CommandContext commandContext) {\n        ProcessDefinition processDefinition = resolveProcessDefinition(document, commandContext);\n        if (processDefinition == null) {\n            throw new FlowableException(\"Cannot find the process definition to migrate to, identified by \" + printProcessDefinitionIdentifierMessage(document));\n        }\n\n        ProcessEngineConfigurationImpl processEngineConfiguration = CommandContextUtil.getProcessEngineConfiguration(commandContext);\n        ProcessInstanceQueryImpl processInstanceQueryByProcessDefinitionId = new ProcessInstanceQueryImpl(commandContext, processEngineConfiguration).processDefinitionId(processDefinitionId);\n        Set<String> processInstanceIdsToMigrate = document.getProcessInstanceIdsToMigrate();\n        if (processInstanceIdsToMigrate != null && !processInstanceIdsToMigrate.isEmpty()) {\n            processInstanceQueryByProcessDefinitionId.processInstanceIds(processInstanceIdsToMigrate);\n        }\n        ExecutionEntityManager executionEntityManager = processEngineConfiguration.getExecutionEntityManager();\n        List<ProcessInstance> processInstances = executionEntityManager.findProcessInstanceByQueryCriteria(processInstanceQueryByProcessDefinitionId);\n\n        for (ProcessInstance processInstance : processInstances) {\n            doMigrateProcessInstance(processInstance, processDefinition, document, commandContext);\n        }\n    }\n\n    @Override\n    public void migrateProcessInstance(String processInstanceId, ProcessInstanceMigrationDocument document, CommandContext commandContext) {","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java#L381-L417","documentation":"When batch-migrating all instances of a process definition, Flowable resolves the target process definition from the migration document (by target id or key/version). If resolution returns null, it throws FlowableException with an identifier message describing what the document asked for, because nothing can be migrated without a valid target definition.","triggerScenarios":"Calling migrateProcessInstancesOfProcessDefinition(sourceDefId, document, commandContext) where the document specifies a target processDefinitionId that doesn't exist, or a key/version combination with no deployed matching definition.","commonSituations":"Target deployment deleted or not promoted to the target environment; typo in target process definition key; specifying a version that was never deployed; tenant mismatch in multi-tenant setups.","solutions":["Verify the target definition exists via RepositoryService.createProcessDefinitionQuery().processDefinitionId(...) before migrating.","Use key-based (latest version) targeting instead of a hard-coded definition id.","Re-deploy the target BPMN to the environment where migration runs.","Check tenant id alignment if using multi-tenancy."],"exampleFix":"// before\ndocument.migrateToProcessDefinitionId(\"orderProcess:4:9999\"); // stale id\nmigrationService.migrateProcessInstancesOfProcessDefinition(srcId, document);\n\n// after\nProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionKey(\"orderProcess\").latestVersion().singleResult();\ndocument.migrateToProcessDefinitionId(pd.getId());","handlingStrategy":"validation","validationCode":"ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()\n    .processDefinitionId(targetDefId).singleResult();\nif (pd == null) throw new IllegalArgumentException(\"Target definition not deployed: \" + targetDefId);","typeGuard":null,"tryCatchPattern":"try {\n    migrationService.migrateProcessInstancesOfProcessDefinition(srcId, document);\n} catch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Cannot find the process definition\")) {\n        logger.error(\"Target process definition missing: \" + e.getMessage());\n    }\n}","preventionTips":["Look up target definition ids from ProcessDefinitionQuery before migrating","Ensure deployments exist in the target environment before running migrations","Prefer key-based targeting over hard-coded definition ids"],"tags":["java","flowable","migration","resource-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-18T11:17:12.947Z"}