{"record":{"id":"0ba78962a6f6740a","repo":"flowable/flowable-engine","slug":"migration-activity-mapping-missing-for-activity-de","errorCode":null,"errorMessage":"Migration Activity mapping missing for activity definition Id:'\" + executionActivityId + \"' or its MI Parent","messagePattern":"Migration Activity mapping missing for activity definition Id:'\" \\+ executionActivityId \\+ \"' or its MI Parent","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java","lineNumber":756,"sourceCode":"                    \t}\n                    \t\n                    \tif (!noChangesInMI) {\n                    \t\tthrow new FlowableException(\"Cannot autoMap activity migration for '\" + executionActivityId + \"'. Cannot migrate arbitrarily inside a Multi Instance container '\" + newFlowElementMIParentId);\n                    \t}\n                    }\n\n                    LOGGER.debug(\"Auto mapping activity '{}'\", executionActivityId);\n                    List<ExecutionEntity> executionEntities = filteredExecutionsByActivityId.get(executionActivityId);\n                    if (executionEntities.size() > 1) {\n                        List<String> executionIds = executionEntities.stream().map(ExecutionEntity::getId).collect(Collectors.toList());\n                        mainProcessChangeActivityStateBuilder.moveExecutionsToSingleActivityId(executionIds, executionActivityId);\n                    } else {\n                        mainProcessChangeActivityStateBuilder.moveExecutionToActivityId(executionEntities.get(0).getId(), executionActivityId);\n                    }\n                    \n                } else {\n                    if (!(currentModelFlowElement instanceof CallActivity)) {\n                        throw new FlowableException(\"Migration Activity mapping missing for activity definition Id:'\" + \n                        \t\texecutionActivityId + \"' or its MI Parent\");\n                    }\n                }\n            }\n        }\n\n        //Explicit Mapping - Iterates over the provided mappings instead, to keep the explicit migration order\n        List<ActivityMigrationMapping> activityMigrationMappings = document.getActivityMigrationMappings();\n\n        LOGGER.debug(\"Process explicit mapping for '{}' activity executions\", executionActivityIdsToMapExplicitly.size());\n        for (\n            ActivityMigrationMapping activityMapping : activityMigrationMappings) {\n\n            if (activityMapping instanceof ActivityMigrationMapping.OneToOneMapping) {\n                String fromActivityId = ((ActivityMigrationMapping.OneToOneMapping) activityMapping).getFromActivityId();\n                String toActivityId = ((ActivityMigrationMapping.OneToOneMapping) activityMapping).getToActivityId();\n                String fromCallActivityId = activityMapping.getFromCallActivityId();\n","sourceCodeStart":738,"sourceCodeEnd":774,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java#L738-L774","documentation":"Thrown when an activity id of a running execution has neither an explicit activity mapping nor a resolvable MI-parent mapping, and the element is not a CallActivity (call activities get a different, more specific error). Migration requires every running activity to be auto-mapped (same id, same semantics) or explicitly mapped.","triggerScenarios":"Calling migrate() where a running execution's activity id was renamed/removed in the new model and the migration document contains no addActivityMapping for it or its multi-instance parent.","commonSituations":"Renaming activity ids in a new definition version; forgetting mappings for active branches; relying on auto-map while the new model changed ids; mapping only some activities of a parallel gateway.","solutions":["Add .addActivityMapping(oldActivityId, newActivityId) for the missing activity in the migration document","Use migrateProcessInstances validation (createProcessInstanceMigrationDocument.validateMigrations / ProcessInstanceMigrationValidationResult) to find all missing mappings before migrating","Keep activity ids stable across definition versions to allow auto-mapping","Also map the multi-instance parent when activities inside an MI element were renamed"],"exampleFix":"// before\nruntimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(v2).migrate(id); // 'reviewTask' renamed to 'approveTask'\n// after\nruntimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(v2)\n    .addActivityMapping(\"reviewTask\", \"approveTask\").migrate(id);","handlingStrategy":"validation","validationCode":"ProcessInstanceMigrationValidationResult result =\n    runtimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(targetDefId)\n        .validateMigrations(instanceIds);\nif (!result.getValidationMessages().isEmpty()) { /* fix mappings first */ }","typeGuard":null,"tryCatchPattern":"try {\n    migrationBuilder.migrate(instanceId);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"Migration Activity mapping missing\")) {\n        // parse ids from message and addActivityMapping for each\n    }\n}","preventionTips":["Always call validateMigrations before migrate","Keep activity ids stable across definition versions","Map renamed activities explicitly in the migration document","Automate a model diff between versions in CI"],"tags":["flowable","migration","activity-mapping","missing-mapping"],"backgroundTag":"missing-required-argument","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"}