flowable/flowable-engine · error · FlowableException

Migration Activity mapping missing for activity definition…

Error message

Migration Activity mapping missing for activity definition Id:'" + executionActivityId + "' or its MI Parent

What it means

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.

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

Example fix

// before
runtimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(v2).migrate(id); // 'reviewTask' renamed to 'approveTask'
// after
runtimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(v2)
    .addActivityMapping("reviewTask", "approveTask").migrate(id);

Defensive patterns

Strategy: validation

Validate before calling

ProcessInstanceMigrationValidationResult result =
    runtimeService.createProcessInstanceMigrationBuilder().migrateToProcessDefinition(targetDefId)
        .validateMigrations(instanceIds);
if (!result.getValidationMessages().isEmpty()) { /* fix mappings first */ }

Try / catch

try {
    migrationBuilder.migrate(instanceId);
} catch (FlowableException e) {
    if (e.getMessage().contains("Migration Activity mapping missing")) {
        // parse ids from message and addActivityMapping for each
    }
}

Prevention

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

When it happens

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

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

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationManagerImpl.java:756

                    	}
                    	
                    	if (!noChangesInMI) {
                    		throw new FlowableException("Cannot autoMap activity migration for '" + executionActivityId + "'. Cannot migrate arbitrarily inside a Multi Instance container '" + newFlowElementMIParentId);
                    	}
                    }

                    LOGGER.debug("Auto mapping activity '{}'", executionActivityId);
                    List<ExecutionEntity> executionEntities = filteredExecutionsByActivityId.get(executionActivityId);
                    if (executionEntities.size() > 1) {
                        List<String> executionIds = executionEntities.stream().map(ExecutionEntity::getId).collect(Collectors.toList());
                        mainProcessChangeActivityStateBuilder.moveExecutionsToSingleActivityId(executionIds, executionActivityId);
                    } else {
                        mainProcessChangeActivityStateBuilder.moveExecutionToActivityId(executionEntities.get(0).getId(), executionActivityId);
                    }
                    
                } else {
                    if (!(currentModelFlowElement instanceof CallActivity)) {
                        throw new FlowableException("Migration Activity mapping missing for activity definition Id:'" + 
                        		executionActivityId + "' or its MI Parent");
                    }
                }
            }
        }

        //Explicit Mapping - Iterates over the provided mappings instead, to keep the explicit migration order
        List<ActivityMigrationMapping> activityMigrationMappings = document.getActivityMigrationMappings();

        LOGGER.debug("Process explicit mapping for '{}' activity executions", executionActivityIdsToMapExplicitly.size());
        for (
            ActivityMigrationMapping activityMapping : activityMigrationMappings) {

            if (activityMapping instanceof ActivityMigrationMapping.OneToOneMapping) {
                String fromActivityId = ((ActivityMigrationMapping.OneToOneMapping) activityMapping).getFromActivityId();
                String toActivityId = ((ActivityMigrationMapping.OneToOneMapping) activityMapping).getToActivityId();
                String fromCallActivityId = activityMapping.getFromCallActivityId();

View on GitHub (pinned to d6d39ce1c6)